login2 PowerLink

This PowerLink allows section and user details to be passed in a secure manner to a script on another web-based application server which may then use this data to perform, for example, a single signon process. The configuration options allow the details to be passed to be selected as well as the parameter names to be used for each value. Additional user-specified parameters may also be defined. The data is passed to the specified URL as a set of name/value pairs in the query string. They are secured by means of a shared secret to generate a message authentication code (MAC) which is also passed to the other application. The technique adopted is identical to that used by Blackboard themselves and as documented in the Automatic Signon Protocol documentation.

A movie illustrating the use of this PowerLink can be found in the Configuration settings section below. A presentation given about the development of the PowerLink is also available from the Blackboard Developers Conference 2007 presentations page on the EduGarage site.

The login2 PowerLink is written for WebCT Vista 4.1.1 (or higher) and WebCT Campus Edition 6.1.1 (or higher). It requires the webctdao.jar module to be installed on the application servers. (From version 2.1 of login2, WebCTDAO 2.3, or higher, is required.)

This PowerLink is installed in the same way as any other WebCT Vista 4 PowerLink:

1. Create a directory called login2 in the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster).
2. Copy the login2.jar file into the login2 directory.
3. Copy the webctdao.jar file into the common directory in the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster). Create this directory if does not already exist.
4. Restart the WebCT service.
5. Log into WebCT as serveradmin.
6. In the Utilities, Settings area click on the link labelled login2 Module in the System Integration column.
7. Enable the tool by selecting the radio button labelled True for the enable setting and click on the Save Values button at the bottom of the page.
8. In the Utilities, PowerLinks Proxy Tools area click on the Add Proxy Tool button.
9. Select login2 Module from the drop-down list and click on the Next button.
10. Enter details as required in the boxes provided; for example:
    • Proxy Tool Name: Connect to Mediawiki
    • Version: 1.0
    • Description: Perform a single signon connection to the Mediawiki tool
    (Note: the Proxy Tool Name is what will appear to Section Designers when they add the tool to their sections.) Click on the Save button.
11. In the Utilities, Settings area click on the link labelled with the Proxy Tool Name entered in the previous step which should appear in the Tools column.
12. Enter the required values for each of the settings (see the Configuration section below for a description of each setting). Lock any values which should not be changed by other users. Click on the Save button.

The login2 PowerLink supports the passing of the following parameters:

Course source parameter (_CourseSource)

The source name of the parent course.

Course ID parameter (_CourseID)

The source ID of the parent course.

Course title parameter (_CourseTitle)

The title of the parent course.

Section source parameter (_SectionSource)

The source name of the section.

Section ID parameter (_SectionID)

The source ID of the section.

Section title parameter (_SectionTitle)

The title of the section.

Section fulltitle parameter (_SectionFulltitle)

A combined title comprising the course title and the section title separated with a hyphen.

Term source parameter (_TermSource)

The source name of the term.

Term ID parameter (_TermID)

The source ID of the term.

Term name parameter (_TermName)

The name of the term.

User source name parameter (_UserSourceName)

The source name of the user

User source ID parameter (_UserSourceID)

The source ID of the user

WebCT user ID parameter (_UserID)

The WebCT user ID

User name parameter (_UserName)

The name of the user comprising the firstname and the last name separated with a space.

User fullname parameter (_UserFullname)

The name of the user comprising their prefix, firstname, other name, last name and suffix. Each element is separated with a space; if an element is empty it is omitted and no space is inserted.

User firstname parameter (_UserFirstname)

The firstname of the user.

User lastname parameter (_UserLastname)

The lastname of the user.

User email parameter (_UserEmail)

The email address of the user.

User status parameter (_UserStatus)

The status of the user being one of the following based on the user's role:

• D: section designer or section instructor
• TA: teaching assistant
• S: student or auditor

User roles parameter (_UserRoles)

A string representation of the array comprising the roles associated with the user with respect to the section; for example [SDES, SINS]. Each role is represented by its code:

• SDES: section designer
• SINS: section instrutor
• STEA: teaching assistant
• SSTU: student
• SAUD: auditor

User-defined parameters (_UserDefined)

Additional parameters specified as name/value pairs separated by semicolons; for example, group=A;login=true which will cause a parameter called group with a value of A and a parameter called login with a value of true to be included in the query string. The values may be static or include any of the variable substitutions supported by the getFormattedName() methods of the LearningContextVO and UserVO objects from WebCTDAO. For example, a user-defined setting of email=%h is equivalent to entering email as the value of the user email parameter. Enter a parameter of phone=%{voice 1};city=%{Locality} to pass the user's telephone number and city.

Timestamp parameter (_Timestamp)

The Unix epoch time (in seconds). Including the time in the parameters being passed can be used to ensure that the resulting URL is only valid for a limited period of time.

Message authentication code parameter (_MAC)

A Message Authentication Code (MAC) which is generated from the other parameters being passed and a shared secret known only to this PowerLink and the application to which the user is being redirected. If this parameter name ends with a 2 a MAC2 calculation is performed, otherwise an "insecure" MAC is calculated. Note that MAC2 calculations use the values of all parameters passed, including any specified in the URL to which the user is being redirected. A normal MAC calculation excludes any parameters included in the redirection URL.

Server-level shared secret (_ServerSecret)

A shared secret value which is only accessible at the server-level (i.e. by logging in as serveradmin). This value is used where no shared secret is specified at the institution or section level (see below).

Institution-level shared secret (_InstitutionSecret)

A shared secret value which is only accessible at the institution-level or above (i.e. by logging in as an institutional administrator, domainadmin or serveradmin). This value is used where no shared secret is specified at the section level (see below).

Shared secret (_Secret)

A shared secret value which is accessible at the section level.

Proxy tool instance ID parameter (_InstanceID)

The ID of the proxy tool instance (during an assisted configuration this value is set to the name of the proxy tool instance as entered by the Section Designer when initiating the creation process).

System version parameter (_SystemVersion)

The version of WebCT (e.g. 18.0.0.135).

Each of these parameters may be passed to the other application by specifying a name for the parameter in the setting field. For example, entering a value of userid against the WebCT user ID setting will add userid=abcdef to the query string (where abcdef is the user's WebCT ID). When the value of a setting is left blank (or set to NA) the parameter is not passed to the other application. Note: a setting value of NA is treated as an empty string; this is a workaround to the SDK bug relating to locked empty settings (see the known issues page for details).

Due to a bug in WebCT, the value for the server- or institution-level shared secret settings should be edited for the module in the System Integration column of the Utilities area and not for the proxy tool itself in the tools column (see the known issues page for details).

The following settings are also used to configure the login2 PowerLink:

URL for external system connection (_URL)

The URL of the script on the application server to which the WebCT user is to be transferred. This script should be written to verify the authenticity of the data being passed to it before performing any necessary actions, such a logging the user in.

Configure this tool externally?

Set to Yes to use the assisted configuration option (see below); otherwise set to No for settings to be edited via the WebCT form.

Name of configure tool button

The label used for the button when using the assisted configuration option (see below).

The following settings are required to have values specified for them:

• URL for external system connection
• Server-level shared secret (default is SECRET)
• Configure this tool externally? (default is No)

 View movie illustration (7:00 minutes)

As a simple example, assume that the following settings have been set and all others are left empty (or set to NA):

When the proxy tool instance is clicked from within a section it will redirect the user to the following URL:
   https://www.other.server.com/script?sectionid=Biology1A&userid=student58&name=George%20Smith&status=S&time=1191196800&mac=D3E170AEED79A10994CB9E128D80FAAF
where:

• the current section has a source ID of Biology1A
• the current user is a student in the section with a WebCT ID of student58 and a name of George Smith
• the current time is midnight on 1 October 2007 (GMT)

Details of how to calculate a MAC are documented in the Automatic Signon Protocol guide from Blackboard which also includes sample code.

The script being redirected to might then perform the following operations:

1. Check the timestamp is within permitted limits of the current time
2. Verify the Message Authentication Code (MAC) by using the shared secret
3. Check that a resource exists on the server for the specified course
4. Check if an account exists for the user and either create one or check the name and status are up-to-date
5. Ensure the user has the appropriate permissions given their status
6. Log the user into the system and redirect them to the main page

An alternative method of configuring a PowerLink is via assisted configuration. Rather than entering the appropriate values for each setting via a generic web form within WebCT, the control of specifying these values is passed to a customised form or script. This not only allows a more user-friendly interface to be provided but also allows related processing to be performed on other web servers (e.g. if connecting to a wiki, a new space can be created when the link is added to the section). The main disadvantage of this configuration method is that values of settings cannot be changed once they have been set.

When using the assisted configuration method for specifying the setting values for the login2 the initial settings should be configured as follows:

URL for external system connection

The URL of the script which will initiate the assisted configuration process. This script would normally reside on the same server as WebCT users will be transferred to via this PowerLink. It may interact with the user to determine their preferences before redirecting them back to this PowerLink with any required settings (see below for more details).

Configure this tool externally?

Should be set to Yes when using the assisted configuration option.

Name of configure tool button

The label used for the button which redirects users to the assisted configuration script.

In addition to the above settings, a name should be specified for any of the parameters which should be passed to the configuration script. For example, when connecting to a wiki, the section ID and title might be passed so that a new space can be created using the same code and main page set up with the title. Additional parameters are automatically included to facilitate the authentication process when returning control back to WebCT. These are:

• ac_guidparam: the name of the parameter used to pass the GUID for the instance of the proxy tool which initiated the configuration request
• GUID parameter: the value of the GUID for the proxy tool instance
• ac_userid: the WebCT ID of the user initiating the configuration request
• ac_returnurl: the URL to redirect to complete the configuration process

The typical tasks of a configuration script are as follows:

Check timestamp

if a timestamp has been passed in the query string (which is recommended to improve security) then this should be checked to ensure that it is within acceptable limits of the current time

Check MAC

if a message authentication code (MAC) has been passed in the query string (which is recommended to improve security) then this should be checked using the shared secret

Confirm action (optional)

if appropriate, interact with the use to confirm the action being requested and/or the values of any optional settings

Initialise system (optional)

perform any processing required to allow the section from which the request is being made to access the application; e.g. for a wiki it may be necessary to create a space dedicated to the section

Configure PowerLink instance

redirect the user to the PowerLink with any changes to the settings passed in the query string

Example

As a simple example, assume that the following settings have been set and all others are left empty (or set to NA):

When an instance of this proxy tool is added to a section, a form is displayed containing a field in which to enter the name for the link and a configure button with the name specified (Create a link in this example). Clicking on this button will redirect the section designer to the following URL:
   https://www.other.server.com/a_script?ac_guidparam=proxyToolCallbackGUID&proxyToolCallbackGUID=1191196800000&ac_userid=instructor1
      &ac_returnurl=https://www.webct.server.com/webct/urw/sslogin2.snSource.siId/cobaltMainFrame.dowebct
      ?appforward=/webct/viewMyWebCT.dowebct&sectionid=Biology1A&title=Biology%201A&time=1191196800&mac=05505DB2C79098D8C1A8D05ABF003882
where:

• the current section has a source ID of Biology1A
• the current user is a student in the section with a WebCT ID of student58 and a name of George Smith
• the current time is midnight on 1 October 2007 (GMT)

After completing any necessary processing, the configuration script should redirect the user back to WebCT passing any parameter values which need to be set, changed or cleared. For example, to configure the proxy tool to be the same as the simple non-assisted example above, the user should be redirected as follows:
   https://www.webct.server.com/webct/urw/sslogin2.snSource.siId/cobaltMainFrame.dowebct?
      appforward=/webct/viewMyWebCT.dowebct&proxyToolCallbackGUID=1191196800000&ac_userid=instructor1&
      _URL=https://www.other.server.com/script&_Title=
This will update the value of the URL parameter, clear the setting for the title parameter; the values of the section ID, time, MAC and shared secret parameters will remain unchanged. (Note that, for security reasons, it is not possible to change the value of any of the shared secrets by passing new values back in the redirection URL.)

The above example, relies on the fact that the URL and title parameters are not locked at a level above the section. This means, therefore, that they are subject to change by a section designer before adding the proxy tool to their section. To avoid this an alternative strategy is to initialise the proxy tool with all the settings required for configuration and single sign-on so that none of them requires changing during the configuration process - the configuration script can be used merely to perform any related processing on the other server. This script can be used to process both a configuration request and a single sign-on request by checking for the presence of one of the configuration parameters (e.g. ac_guidparam). If the parameter is present then the configuration action is performed, if it is not then a single sign-on action is performed. All the proxy tool settings may then be locked so that section designers are unable to tamper with them, either intentionally or unintentionally! The video illustration presented in the Configuration section above show this technique in action.

If you experience any problems using this PowerLink try the following to trace the cause:

• inspect the webct.log file for any reported errors
• check that the URL being used by the proxy tool instance is valid
• inspect the log files for the server to which the user is being redirected to see if a connection had been recorded
• add a line containing log4j.category.com.spvsoftwareproducts=DEBUG to the log4j.properties file in the serverconfs directory; this will increase the logging level for the PowerLink

Upgrade instructions

The following instructions provide a guide to the process of upgrading to a later release of this PowerLink. You are, however, strongly advised to follow them in conjunction with the installation instructions above, the administrator documentation provided for your release of WebCT, and to first try them on a test server.

Upgrading from version 1.0.00 to version 1.0.01

1. Shut down WebCT
2. Remove the old PowerLink jar file
3. Add the new PowerLink jar file
4. Restart WebCT

Any existing proxy tool instances should continue working as before.

Upgrading from version 1 to version 2+

1. Make a note of any values entered for the server- or institution-level shared secret settings (as these will need to be re-entered as part of the upgrade process)
2. Shut down WebCT
3. Remove the old PowerLink jar file
4. Remove the authmoduledata utility file (unless it is being shared by other PowerLinks)
5. Add the new PowerLink jar file
6. Ensure the WebctDAO utility file is available on the server
7. Restart WebCT
8. Log into WebCT as serveradmin
9. In the Utilities, Settings area click on the link labelled login2 Module in the System Integration column
10. Enable the tool by selecting the radio button labelled True for the enable setting, re-enter any value entered for the server-level shared secret setting, and click on the Save Values button at the bottom of the page
11. If a value was previously entered for the institution-level shared secret settings this should also be re-entered at the server, domain or institution level, as appropriate

After following the above steps. existing proxy tool instances should continue to work but none of the new settings will be available. To enable the new settings continue as follows:

1. In the Utilities, PowerLinks Proxy Tools area click on the Proxy Tool Name for a proxy tool created based on this PowerLink
2. Do not change the values of any settings but just click on the Save button at the bottom of the page
3. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
4. Tick the Unlock this setting box against the Enable Tool setting
5. Click on the Save button at the bottom of the page
6. Repeat the above steps for all proxy tools based on this PowerLink

The above steps will leave the proxy tool disabled in each section irrespective of any previous setting. It may be enabled for all sections as follows:

1. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
2. Select True for the Enable Tool setting
3. Click on the Save button at the bottom of the page

The enable setting may also be changed at lower levels of the learning context hierarchy (for example, at the section level). However, there is no known way of restoring the values for the enable setting as they existed before the upgrade.

Upgrading from version 2.0 or 2.1

1. Shut down WebCT
2. Remove the old PowerLink jar file
3. Add the new PowerLink jar file
4. Ensure the WebctDAO (2.3 or later) utility file is available on the server
5. Restart WebCT

Any existing proxy tool instances should continue working as before.

This work is written by Stephen Vickers and is released under a Creative Commons GNU General Public Licence. The login2 PowerLink can be downloaded from OSCELOT where it is also possible to report bugs and submit feature requests.