CAS 2.0 Authentication for Blackboard

blackboard-cas is a CAS authentication module for Blackboard. It utilizes the CAS 3.1 client library in order to connect to CAS 2.x/3.x servers (using the CAS 2.0 protocol).

blackboard-cas is based on CasAuthenticationModule, developed by the University of Bristol.

Configuration

Before building, you should edit the settings in build.properties. Settings include:

blackboard.home: The path to your Blackboard instance.
blackboard.java.home: The path to the JDK used by Blackboard.
blackboard.tomcat.version: The version of Tomcat Blackboard is using. Supported versions: 3, 4, 5, 6.
blackboard.url: The HTTP protocol and domain name to your Blackboard instance (e.g. http://blackboard.some.edu).
blackboard.cas: The base URL to your CAS server (e.g. http://sso.some.edu/cas).
blackboard.cas.isdefault: If true, CAS is used as the default authentication module.
blackboard.cas.logout_completely: If false, logging out of Blackboard won't log the user out of CAS.
blackboard.cas.use_post: If true, CAS redirects back to Blackboard using a POST request. This should be enabled if you've applied the recent XSS security patch regarding login redirection.

Building

Make a directory named lib in the blackboard-cas folder. It will need the following files (from cas-client-3.1.10-release.zip):

cas-client-core-3.1.10.jar
commons-logging-1.1.jar
xmlsec-1.3.0.jar

You'll also need an instance of Blackboard in C:\blackboard in order to build.

You'll need apache ant (1.8.2) and apache maven (2.2.1) to run the build. Once you have this, you can build with ant:

C:\folder\with\ant.bat -lib lib

The build process will execute the main method of the plugin, and it should crash with an invalid ticket exception. If you get a different exception, the plugin was probably unable to connect to your CAS server.

Installation

Copy the following files into C:\blackboard\systemlib:

dist\cas-bbauth.jar
lib\cas-client-core-3.1.10.jar
lib\commons-logging-1.1.jar
lib\xmlsec-1.3.0.jar

Then update C:\blackboard\config\authentication.properties, add the settings from dist\cas-authentication.properties to it, and change bbconfig.auth.type in C:\blackboard\config\bb-config.properties to cas.

Copy cas-common.classpath into C:\blackboard\config\tomcat\classpath.

Customize the following blackboard files by adding the lines immediately following each filename listed below, (including any leading spaces):

C:\blackboard\system\build\bin\launch-app.bat:

  rem # CAS
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;cas-bbauth.jar
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;cas-client-core-3.1.10.jar
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;xmlsec-1.3.0.jar
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;commons-logging-1.1.1.jar
  rem # CAS

C:\blackboard\system\build\bin\launch-tool.bat:

  rem # CAS
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;cas-bbauth.jar
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;cas-client-core-3.1.10.jar
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;xmlsec-1.3.0.jar
  set THIRD_PARTY_CP=%THIRD_PARTY_CP%;commons-logging-1.1.1.jar
  rem # CAS

C:\blackboard\apps\collab-server\config\wrapper.conf.bb:

# CAS
# only use cas-bbauth.jar here if collab and app server on same box 
wrapper.java.classpath.43=@@bbconfig.basedir@@/systemlib/cas-bbauth.jar
wrapper.java.classpath.44=@@bbconfig.basedir@@/systemlib/cas-client-core-3.1.10.jar
wrapper.java.classpath.45=@@bbconfig.basedir@@/systemlib/xmlsec-1.3.0.jar
wrapper.java.classpath.46=@@bbconfig.basedir@@/systemlib/commons-logging-1.1.1.jar
# CAS

C:\blackboard\apps\snapshot\config\env.cmd.bb:

rem # CAS
set CP=%CP%;%BBLIB%\cas-bbauth.jar
set CP=%CP%;%BBLIB%\cas-client-core-3.1.10.jar
set CP=%CP%;%BBLIB%\xmlsec-1.3.0.jar
rem set CP=%CP%;%BBLIB%\commons-logging-1.1.1.jar
rem # CAS

C:\blackboard\apps\content-exchange\bin\content-exchange.bat.bb:

rem # CAS
set CP=%CP%;%BBLIB%\cas-bbauth.jar
set CP=%CP%;%BBLIB%\cas-client-core-3.1.10.jar
set CP=%CP%;%BBLIB%\xmlsec-1.3.0.jar
rem set CP=%CP%;%BBLIB%\commons-logging-1.1.1.jar  # file already has this elsewhere
rem # CAS

Now restart the server and test your implementation.

Issues

Are proxy tickets supported?

No. The CAS 3.1 client library provides support for proxy tickets, but this is not yet implemented in blackboard-cas.

Why am I getting java.security.cert.CertificateException errors?

Your CAS server is using an SSL certificate that isn't in Java's database of trusted keys (known as the keystore). If you're using a self-signed certificate for testing purposes, you should add it to either Java's keystore or Blackboard's keystore, using keytool.

With BB9, the home page displays with a login form, instead of just a login button (as in BB8), but I can't log in with CAS using this form.

You will need to replace the login form with a login link (or something similar), by customizing the login page as follows:

on BB: Go to Administrator > Brands and Themes > Customize Login Page. Click Download Custom Login Page and download the file.
On your local system: Edit the downloaded Custom Login Page file (or edit a copy of it). Replace the login form with a link to the login url (.../webapps/login). Save the new login file.
On BB: Go to Administrator > Brands and Themes > Customize Login Page. Click Upload Custom Login Page and upload the new login file.

View the blackboard home page - you should now see the link and no longer see the login form. This gets you the functionality - you may want to add other html or css to make it look nicer.

With BB9, an authenticated user who does not have a record in the database goes into an infinite loop.

Setting the message that a user is not in the db does not seem to be working in BB9 the way it works in BB8. Use the lookup_user_in_BB property and set it to true, to enable a manual/explicit check for the user in the database.