confluenceSSO PowerLink

This PowerLink allows a Section Designer to automatically create and manager wiki spaces in Confluence, adding links to these spaces within WebCT. Staff and students may be given different permissions within this wiki space and their user accounts are automatically added to the wiki when they connect.

The confluenceSSO PowerLink is written for WebCT Vista 4.2.0 (or higher) and WebCT Campus Edition 6.2.0 (or higher). It requires serveradmin access to WebCT for installation and an administrator account on the Confluence server to operate. A list of dependencies is provided in the Installation section below. The PowerLink has been tested with a wide range of Confluence versions from 2.5 up to (and including) 2.10.1.

Wiki space creation

When a Section Designer first adds an instance of this proxy tool to their section (via the Add Content Link) the following actions take place:

1. connect to the SOAP service on the Confluence server
2. page is displayed requesting confirmation that a wiki space should be created
3. a wiki space is created in Confluence
4. give the default administrators group (if defined) full permissions to the space
5. create a users group for the space and give it the specified permissions
6. create an administrators group for the space and give it the specified permissions
7. complete the initialisation of the proxy tool instance via a callback to the assisted configuration URL

A wiki space is created with the following details:

• key - the specified prefix string followed by the section's source name and ID (with a separator character between them); all characters which are not letters or digits are substituted with a letter x (to conform to the Confluence naming rules) and the whole string is changed to lower case (so that the key is the same as the prefix to the names of its related groups)
• name - the name of the section's parent course combined with the name of the section (separated with a hyphen); if a name prefix setting is specified then this is added to the beginning of the name (followed by a space)

(Note that the format of space keys and names can be changed via configuration settings.)

For example, with a key prefix setting value of Z, a name prefix setting value of WebCT: and a section with a source name of WebCT, a source ID of URN:ABC-123-def, a title of Semester 1 and a parent course title of Philosophy 3, the wiki space created in Confluence will have a key of zwebctxurnxabcx123xdef and a name of WebCT: Philosophy 3 - Semester 1.

The groups for a wiki space are created with names comprising the key for the wiki space followed by either -users or -administrators; for example, zwebctxurnxabcx123xdef-users.

Wiki user creation

When a user first clicks on the link created to a confluence wiki space the following actions take place:

1. create a new user account in Confluence
2. add the user to the users group for the wiki space
3. if the user is not a student or auditor, add them to the administrators group for the wiki space
4. redirect the user to log into the Home page for the wiki space

A user account is created with the following details:

• name - the key of the wiki space followed by an underscore and the user's WebCT ID
• fullname - the users's firstname and lastname as recorded in WebCT separated by a space followed by the key of the wiki space in brackets
• email - the user's email address as recorded in WebCT
• password - an uppercase message authentication code (MAC) using the shared secret setting

(Note that the format of fullnames can be changed via a configuration setting.)

A configuration setting provides the following options for the domain of a user account:

• Space - a separate user account is created for each user in each wiki space (this is the default setting)
• Section - a single account for each user is used for all wiki spaces within a section
• Server - a single account for each user is created for all wiki spaces for all sections

The user domain selected essentially determines which wiki spaces a user can access from the Dashboard page in Confluence. By default a user is a member of the default confluence-users group and will have access to the wiki space for which their user account has been created as well as any other wiki spaces on the Confluence Server which have granted permissions to this group or can be accessed anonymously. Normally this would only be non-WebCT wiki spaces unless the default permissions for a WebCT wiki space have been changed. If an alternative default users group is specified in the configuration settings then the list of available wiki spaces will depend upon the permissions assigned to this group (rather than confluence-users) as well as all of those spaces available anonymously. Using such a group setting also provides a quick method of disabling all access to wiki spaces via WebCT (by merely removing the global access permissions to this group). Note that users are only added to this group when their accounts are created; the group memberships of any existing user accounts are not changed.

The username created will consist of their WebCT ID with a prefix which depends upon the selected domain:

• Space - a prefix of the wiki space code is used
• Section - a prefix of the default wiki space code for the section is used
• Server - no prefix is used

In addition to a prefix based on the user domain, a configuration setting can be used to specify an initial prefix for all user accounts; if specified, this is inserted before the domain prefix. Any prefixes are separated from the WebCT ID with an underscore.

The data used to generate a user's password depends upon the selected user domain:

• Space - sourcedid (source name and ID) of both the section and the user, and the group key of the wiki space (if any)
• Section - sourcedid (source name and ID) of both the section and the user
• Server - sourcedid (source name and ID) of the user

If the configuration setting to reset the password on each connection is selected, then the current Unix epoch time in milliseconds is also included. The data fields are encrypted using the specified shared secret to form a Message Authentication Code (MAC) which is then used as the user's password. Note, that changing the user domain setting will alter the password generated for a user which will prevent them from connecting to the wiki unless they are either a new user or the reset password on each connection setting has been enabled. The same is true if any changes arise in a user's sourcedid or the section's sourcedid (except where the server user domain is being used). Since the password is needed to connect a user to Confluence, it is not possible for users to both connect via WebCT as well as log in directly (this limitation is particularly relevant when using the server user domain but only applies when direct logins are authenticated against the Confluence database).

For example, when using the Space user domain and a username prefix of w, a user with a WebCT ID of auser, a firstname of George and a lastname of Brown being added to the above wiki space, would be given a username of wzwebctxurnxabcx123xdef_auser and a name of George Brown (zwebctxurnxabcx123xdef). If this user had a source name of WebCT and a source ID of URN:X-abcdef-123456 and the shared secret for this PowerLink was set to Confluence then their password would be set to C4C2005226815C22713BBD16751D26A9. Details on generating MACs can be found, for example, in the WebCT documentation for the Automatic Signon Protocol. If a section's source name or ID changes this will affect the passwords calculated for any users who have already connected to the wiki space. In this situation setting the reset user passwords on each connection option to true will ensure that the new password is updated in Confluence and users are able to continue logging in. If a user's source name or ID change then their new password can just be calculated manually (or found from the log files) and updated in Confluence by an administrator.

The same username would apply if the Section user domain were used instead; this name would apply to all wiki spaces within the section. When using the Server user domain the username for all the user's wiki spaces accessed from all sections within WebCT would be w_auser with a password of B5008FF3D3A31BE1736B8B2E3460EEE5. If no username prefix were specified then the username would be the same as the WebCY ID, auser.

On subsequent connections by the same user, their name and email details are updated in Confluence if they have changed (unless this setting has been disabled). If a wiki space no longer exists then an error message is displayed.

Wiki space administration

When the option has been enabled, a wiki space administration page is displayed when a Section Designer selects the preview option for an instance of the wiki proxy tool. This page provides a list of the wiki spaces which have been created for the section. A space may be deleted from the Confluence server by selecting the space and clicking on the Delete button. This will perform the following actions:

1. remove the wiki space
2. remove the users group associated with this wiki space
3. remove the administrators group associated with this wiki space
4. remove or disable each user account for the wiki space

This process deletes all the contents of the wiki, so it is advisable to backup the space before deleting it. This can be done from within the Advanced section of the wiki. The default setting is for user accounts to be deleted as well. When using the Space user domain, user accounts will be deleted with the wiki space. If the Section user domain is being used then user accounts are only deleted if they do not belong to any wiki space groups. Under the Server user domain a user account is only deleted if a Confluence users group has been specified and this is the only group which the user is a member of.

A refresh option is also provided on the wiki space administration page. This option will check all user accounts which are members of the wiki space's administrators and/or users groups and remove those for users who are no longer enrolled in the section. If this is the only wiki space to which the user account has access, then the account is also deleted from the server.

The Confluence remote API does not provide a method for returning a list of users for a given wiki space or group, so deleting and refreshing users involves processing a list of all users registered on the Confluence server. For a large Confluence installation this may be a time-consuming exercise and so this option may be best disabled in such circumstances. Whilst this will mean that the user accounts will remain on the Confluence server they should are not usable without the password and they will not belong to any groups for the WebCT wiki spaces.

Multiple wiki spaces

A configuration setting allows more than one wiki to be created for each section. If this option is enabled then when a Section Designer attempts to add a new instance of this proxy tool to their section, a form is presented which lists any wiki spaces which have already been created and, if the maximum number has not yet been reached, provides a control for entering the name for a new space. The new proxy tool instance may be linked to one of the existing spaces or to a new one. Any wiki spaces which are given a name are also allocated a space group key which is added as a suffix to the space key (separated from the default wiki space key with a letter w. This group key is automatically generated and saved in the proxy tool instance settings via a redirection to the assisted configuration URL. The group key is a sequence of one of more lower case letters starting with a. For example, if the first additional wiki space for the above example section is given a name of Group A then its space key will be zwebctxurnxabcx123xdefwa and its name will be WebCT: Philosophy 3 - Semester 1 (Group A). Using the same example user details as above (and assuming the Space user domain is selected), the username for this wiki space would be wzwebctxurnxabcx123xdefwa_auser with a name of George Brown (zwebctxurnxabcx123xdefwa) and a password of 9021296DFCE3F9E05A7612FC4C753C58.

If for any reason the maximum number of wiki spaces is reduced to below the number of spaces already created, any existing proxy tool instances will continue to work but it will not be possible to add any more. If the maximum number of spaces is reset to 1 then only the default space (no group key) can be added to the section as a new instance of the proxy tool.

Synchronising groups

Version 2 of this PowerLink introduced an option to synchronise learning groups within the WebCT section with Confluence groups. This allows a wiki space to be created for a section within which different groups of users are given access to different pages based on their membership of groups within WebCT. For example, this could be used to give private areas for student group work without the need to create a separate wiki space for each group.

The name of the group created in Confluence comprises the key for the wiki space followed by two dashes ("--") and the name of the learning group as specified in WebCT. Any characters in the learning group name which are not letters or numbers are converted to a dash. For example, in the wiki space zwebctxurnxabcx123xdef, a learning group called Wiki Group 1 will be created as a Confluence group named zwebctxurnxabcx123xdef--wiki-group-1. If a user group name prefix setting is specified, then learning groups with names which do not start with this prefix will not have Confluence groups created.

Membership of the Confluence groups is updated automatically when users connect to the wiki space; this includes removing them from any groups to which they no longer belong. In addition, the refresh option on the wiki space administration page can be used to reset the membership of each user group - this will delete any groups which already exist, create a Confluence group for each learning group (except for those which do not have names which match any specified prefix), and add those members to the groups who have already have a user account. Any users who do not yet have accounts will be added to the groups when they connect to the wiki space; user accounts are only ever created in Confluence when the user connects.

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

1. Create a directory called confluenceSSO in the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster).
2. Copy the confluenceSSO.jar file into the confluenceSSO directory.
3. Copy the dependent jar library files into the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster). The confluence-soap-0.3.jar and xercesImpl.jar files should be placed in the same location as the confluenceSSO.jar file. If desired, an alternative location of the common directory may be used for the remaining dependent files; this would allow them to be shared with any other PowerLinks with the same dependencies.
4. Restart the WebCT service.
5. Log into WebCT as serveradmin.
6. In the Utilities, Settings area click on the link labelled confluenceSSO Module in the System Integration column.
7. Enable the tool by selecting the radio button labelled True for the enable setting and enter the required values for each of the settings (see the Configuration section below for a description of each setting). 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 confluenceSSO 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: Confluence wiki space
    • Version: 1.0
    • Description: Connect to a wiki space in Confluence.
    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. Clear the tick in the Lock this setting checkbox for the Enable setting and click on the Save button. Select the tool again if you wish to enable the tool on the server by default (rather than having section designers enable the tool within each section before it can be used).

 View movie illustration (4:21 minutes)

The confluenceSSO PowerLink depends upon the following Java library files:

• activation-1.0.2.jar
• axis-1.3.jar
• axis-jaxrpc-1.3.jar
• axis-saaj-1.3.jar
• axis-wsdl4j-1.5.1.jar
• commons-discovery-0.2.jar
• confluence-soap-0.3.jar
• javamail-1.3.2.jar
• xercesImpl.jar
• webctdao.jar (version 2.3 or higher)

The confluence-soap-0.3.jar comes from the Confluence Maven 2 SOAP library project. A copy of each of the above dependencies is provided in a separate download file; except for webctdao.jar which is available from the WebCTDAO documentation area.

Note: the xercesImpl.jar library file is required because of a bug with the version of WebLogic used by WebCT Vista 4.2. Making a copy of this file available to the PowerLink provides a workaround to this bug for this application (see the known issues page for details).

The confluenceSSO PowerLink has the following custom configuration settings:

Notes:

1. The level specifies the level of the learning context hierarchy at which this setting should be specified; it may, of course, be inherited from a higher level except for the space code suffix which is set automatically at the section level. Due to a bug in WebCT, value for settings at levels above Section 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).
2. 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).
3. This group can be used to limit access to other non-WebCT wiki spaces on the Confluence server; when used the Confluence administrator should permit this group to access Confluence via the Global Permissions page.
4. A secret value of SECRET is ignored and should not be used. Changing this value will invalidate passwords for existing user accounts unless the Reset user password on each connection option is enabled.
5. The permissions should be a comma separated list comprising any of the following options:
   • VIEWSPACE
   • EDITSPACE
   • EXPORTPAGE
   • SETPAGEPERMISSIONS
   • REMOVEPAGE
   • EDITBLOG
   • REMOVEBLOG
   • COMMENT
   • REMOVECOMMENT
   • CREATEATTACHMENT
   • REMOVEATTACHMENT
   • REMOVEMAIL
   • EXPORTSPACE
   • SETSPACEPERMISSIONS
   The options are case insensitive and any spaces will be removed automatically.
6. Setting the maximum number of spaces to 0 will disable this tool; all negative values will allow an unlimited number of spaces to be created.
7. It is strongly recommended that these settings are not changed after wiki spaces have been created; doing so may affect access to existing spaces
8. It is strongly recommended that these settings are not changed after wiki user accounts have been created; doing so may affect access to existing spaces
9. The space key and space name prefixes may also be used to specify the format of key/name by including variable substitutions supported by the LearningContextVO.getFormattedName() method (see the WebCTDAO documentation area for details). For example, the default space key prefix is equivalent to %F %G and the default space name prefix is equivalent to WebCT: %1 - %C. If no variable substitutions are included in the setting value then the default substitutions are automatically added; if the prefix includes a percentage sign then it is assumed to already contain the required substitutions. For space keys it is important to use variable substitutions which guarantee a unique value for each section (remembering that any characters not supported by Confluence will be automatically changed to x). Thus, for WebCT systems on which the source ID of a learning context is unique, a space key prefix of %G could be safely used. Space names are only used for display purposes and so their uniqueness is not essential, but recommended.
10. The format of a user's display name may use any of the variable substitutions supported by the UserVO.getFormattedName() method (see the WebCTDAO documentation area for details). In addition, the %a %b (%@) substitution can be used to represent the user's domain. For example, the default display name format is %a %b (%@) (or just %a %b when the server-level domain is selected).
11. This setting currently supports values of GET and POST, The former will use a simple redirect to transfer a user to the Confluence server. However, the query string for the URL used in this redirect will include the user's password and potentially provide a bookmarkable URL for direct access to Confluence. The password may also be included in the server log files. To improve security an alternative is provided using a web form which is automatically submitted using JavaScript. The form submits the username and password as POST parameters. Ideally a web service would be used to obtain a session ID so that password details do not need to be passed via the user's browser, but at present such as service is not available. (NB To further enhance the security of connections to Confluence the Reset user password on each connection setting may also be used.)

Adding a new instance

Use the Add Content Link button from the Build tab to create a new instance of this PowerLink in a section. If the tool has been configured to only permit a single space per section then a confirmation request is displayed (as illustrated). If a space has already been created then the instance is created immediately.

 View movie illustration (1:27 minutes)

When more than one wiki space is permitted per section, a text box is provided to give additional spaces a name. These spaces are referred to as group spaces and the group name entered is appended to the standard name comprised of the course and section titles. The space created without a group name is referred to as the default space. To create a group space, select the New group space radio button and enter a group name. A group code will automatically be generated (starting with a for each additional space created and used as a suffix to the space key so that each space has a unique key.

 View movie illustration (2:41 minutes)

From the Teach and Student View tabs, clicking on the proxy tool instances added to the section will connect users directly to the wiki space. On the first attempt a user account will be automatically created within Confluence. Staff will be given additional permissions within the space (depending upon the configuration settings of the tool and any changes made after the space has been created).

If the option has been enabled for the tool, then selecting the Preview action link next to any instance of the tool on the Build tab will display an administration page which lists all the existing spaces for the section. Select the radion button next to a space title and click on the Delete button to delete the space, its associated groups and its users (unless this option has been disabled).

See movie illustration above.

The confluenceSSO PowerLink is an outbound authentication module extending the com.webct.platform.sdk.security.authentication.module.AuthenticationModule class. It applies the following techniques:

• Assisted configuration (from within the PowerLink itself rather than using scripts on a separate server)
• Confluence remote API to add, update and remove wiki spaces, groups and user accounts
• Velocity for preparing web pages for display
• Logger used to log actions and errors at different stages of execution
• Deployable component configuration settings restricted to different levels of the Learning Context hierarchy

A list of dependent files is provided in the Installation section above.

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 to connect to Confluence is valid
• ensure the Confluence administrator username and password are correct
• inspect the Confluence server log files for connection and error messages
• test the connection to the Confluence server using the Confluence Command line interface
• 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 to version 1.0.01

1. Shut down WebCT
2. Remove the old PowerLink and confluence-soap-model library jar files
3. Add the new PowerLink and confluence-soap-model library jar files
4. Restart WebCT

Any existing proxy tool instances should continue working as before.

Upgrading to version 2.0

1. Make a note of any values entered for all the configuration settings not set at the section level (as these will need to be re-entered as part of the upgrade process); note that these may have been entered at different levels of the learning context hierarchy
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 (version 2.1 or 2.2) 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 confluenceSSO Module in the System Integration column
10. 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
11. Re-enter at the appropriate level of the learning context hierarchy all the configuration settings which are not defined at the section level

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 to version 2.1

Note that that this version also requires WebCT AP2 (or higher).

1. Make a note of any values entered for all the configuration settings not set at the section level (as these will need to be re-entered as part of the upgrade process); note that these may have been entered at different levels of the learning context hierarchy
2. Shut down WebCT
3. Remove the old PowerLink jar file
4. Remove the old confluence-soap-model library jar file
5. Add the new PowerLink jar file
6. Add the new confluence-soap-model library (version 0.3) jar file
7. Restart WebCT
8. Log into WebCT as serveradmin
9. In the Utilities, Settings area click on the link labelled confluenceSSO Module in the System Integration column
10. 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
11. Re-enter at the appropriate level of the learning context hierarchy all the configuration settings which are not defined at the section level
12. In the Utilities, PowerLinks Proxy Tools area click on the Proxy Tool Name for a proxy tool created based on this PowerLink
13. Do not change the values of any settings but just click on the Save button at the bottom of the page
14. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
15. Tick the Unlock this setting box against the Enable Tool setting
16. Click on the Save button at the bottom of the page
17. Repeat the last 5 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 to version 2.2

1. Make a note of any values entered for all the configuration settings not set at the section level (as these will need to be re-entered as part of the upgrade process); note that these may have been entered at different levels of the learning context hierarchy
2. Shut down WebCT
3. Remove the old PowerLink jar file
4. Add the new PowerLink jar file
5. Ensure the WebctDAO (version 2.3) utility file is available on the server
6. Ensure the new confluence-soap-model library (version 0.3) jar 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 confluenceSSO Module in the System Integration column
10. 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
11. Re-enter at the appropriate level of the learning context hierarchy all the configuration settings which are not defined at the section level

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.

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