Appendix D: Original Instructions for Shibboleth Single Sign-on for WebCT/Blackboard Vista/CE

To enable Shibboleth single sign-on for a Vista/CE installation, you must install the Shibboleth authentication module for Vista/CE. The Shibboleth authentication module (a.k.a. PowerLink) validates the incoming Shibboleth ticket, sets the Vista/CE username to the username (net ID) that Shibboleth provides, and redirects the user to the My Blackboard page. This document explains how to configure the plugin and the Shibboleth identity provider.

Thanks to Bonnie Ferguson (b.ferguson@kent.ac.uk) for providing these instructions.

Requirements

• Vista 3+ / CE 6+ (in this document, sometimes referred to as vista-server.example.org) You must have the usernames and passwords for the serveradmin and institution admin accounts in order to configure the authentication module and logging settings. The URLs for logging in to Vista/CE are:
  • http://<vista_host_and_port>/webct/logonDisplay.dowebct (serveradmin)
  • http://<vista_host_and_port>/webct/ (admin)
• The Shibboleth authentication module, which can be downloaded from the Blackboard Powerlinks Developers Network. The Developers Network is open to all Vista 3+/CE 6+ customers (registration is required). It provides support forums, documentation, and open source PowerLinks that have been developed by Blackboard Powerlinks developer community.
• The Blackboard Vista PowerLinks SDK, (optional) which is available to Vista and CE customers. The SDK includes documentation, code samples, and libraries for developing custom PowerLinks. It can be downloaded from the Behind the Blackboard site. This is only necessary if you want to customize the module, not if you just want to use it.
• A Shibboleth Identity Provider (in this document, sometimes referred to as shibidp.example.org). You will need to be able to access the configuration and logs. You will need the following Shibboleth IdP values (from the idp.xml file):
  • Provider ID
  • Attribute authority URL
  • User attribute to be used as the User ID.

NOTE: You do not need a separate Shibboleth Service Provider. The Shibboleth module turns WebCT into a Service Provider.

Caveats

• Users authenticating via Shibboleth must already exist in Vista/CE.
• The Vista/CE username must be the same as the Shibboleth provided Net ID
• If designers want to use WebDAV, they will still require a password in WebCT. This is a limitation of WebDAV clients and a general problem with any Web-based SSO system. The password they are prompted for, can be stored in any supported password system such as LDAP.
• If the Shibboleth Identity Provider is using SSL, Identity Provider SSL certificates MUST be signed by a proper CA certificate. It can be an internal CA, but cannot be self-signed certificates due to security restrictions by BEA WebLogic 8.1 SSL implementation.

Installation

1. Download the Jakarta Commons Codec library (current version is commons-codec-1.3.jar) from Apache Jakarta Commons. This library is used to process the Base64 encoding used in Shibboleth.
2. Log in to the Blackboard PowerLinks Developers Network. (Vista/CE customers can register for a free account.)
3. Download the updated Shibboleth authentication module from  http://devnet.webct.com/contrib/authentication/Shibboleth/new_shib/.

   NOTE: The original Shibboleth authentication module is still available but it should not be used due to certain limitations.

4. Unzip the archive. The pre-built Shibboleth authentication module (shibbolethsso.jar) is located in the dist directory.
5. Deploy the authentication module on the Vista/CE server as you would any other deployable component. Some steps are slightly different depending on your version of Vista/CE. For details, see the PowerLinks SDK documentation or Administrators Guide. The basic steps are:
   1. Create a new directory in your <WebCTDomain>/deployablecomponents directory called shibbolethsso.
   2. Copy the commons-codec-1.3.jar and shibbolethsso.jar files into this directory.
   3. Restart Vista/CE and check the logs for errors. (Close any application sessions that you have open, since this slows the restart process)
   4. Enable and configure the Shibboleth module. Log in as serveradmin and go to the Settings tab.
   5. In the Deployable Components settings, ensure Allow deployable components is true.
   6. In the Shibboleth Inbound Module settings, change the following attributes:

      Enable	true
      Shibboleth AA url	Change this to the Shibboleth Identity Provider's attribute authority that the module will contact for the user attributes, such as the UserId. This value can be found in the idp.xml file. For example: https://shibidp.example.org:443/shibboleth-idp/AA
      Shibboleth Origin URI	Origin is the Shibboleth 1.2 name for the Identity Provider, so use the providerId that is configured at the beginning of the Shibboleth identity Provider's idp.xml file. If your Shibboleth IdP has been registered with a federation such as InQueue, the providerId is the URI that was assigned by InQueue when you were accepted into the federation. Configuring a single Identity Provider limits us to using only one, though you can probably replace this with the federation WAYF URL.
      Shibboleth UserID Attribute	If necessary, change this value to the LDAP attribute that you are using as the Vista/CE username. For example, urn:mace:dir:attribute-def:uid.
      SHIRE URI used for Authorization	Set this to the URL used to invoke the authentication module. For example: http://vista-server.example.org:80/webct/urw/ssinboundShibboleth.si<ims_id>.sn<ims_name>/cobaltMainFrame.dowebct SHIRE is the Shibboleth 1.2 term for the "Shibboleth Indexical Reference Establisher". This attribute is not currently being used, because it is being set in the URL that we build later, but it seems good practice to have the correct value for this attribute.

6. Configure the Vista/CE logger settings. (These settings are reset each time Vista/CE is restarted, so be sure to update them again after each restart.) Log in to Vista/CE as serveradmin, go to the Logging tab, and set the following loggers to DEBUG level:
   • VistaSDK
   • coreservice.security
   • coreservice.deployablecomponents

   add a new logger and set the log level to DEBUG: com.webct.sso.shibboleth.ShibbolethInboundModule

   The log messages will be output to <WebCTDomain>/logs/webct.log and <WebCTDomain>/logs/webct_sdk_log.log. The first one will have all the really interesting messages. The second contains message relating to the deployment of the authentication module.

7. Add WebCT as an Assertion Consumer Service to the ShibID metadata.xml file so that it recognises the attribute request coming from Vista/CE. For example:

   <AssertionConsumerService
       Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"
       Location="http://vista-server.example.org:80/webct/urw/ssinboundShibboleth.siURN:X-WEBCT-VISTA-V1:c4d1111-810c-c843-111-1112da97e1cb.snWebCT/cobaltMainFrame.dowebct"
       index="2" />
   

8. Create a custom Vista/CE login page. You can use the sample login page in the html directory of the Shibboleth module as a base for your custom login page.

   The login form must be submitted to the URL that will trigger Shibboleth authentication. This URL consists of:

   • the Shibboleth Identity Provider single sign-on URL (https://shibidp.example.org/shibboleth-idp/SSO)
   • the shire parameter, which is the URL that is used to invoke the Shibboleth authentication module. For example:

     http://vista-server.example.org:80/webct/urw/ssinboundShibboleth.si<ims_id>.sn<ims_name>/cobaltMainFrame.dowebct &

     There are a couple ways to find the institution's IMS ID and name. One is to log in to Vista/CE as the domain administrator and view the institution's properties. Another is to run siapi.sh p from the command line (in the WebCT domain directory).

   • the target parameter (http://vista-server.example.org:80/webct)

     NOTE: You must include a non-empty target parameter in the query string, even though the value is not used.

   Escape sequences must be used to replace the ":" and "/" characters in the query string (: =  %3A and / = %2F), resulting in something like this:

   https://shibidp.example.org/shibboleth-idp/SSO?shire=http%3A%2F%2Fvista-server.example.org%3A80%2Fwebct%2Furw%2FssinboundShibboleth.siURN:X-WEBCT-VISTA-V1:c4d61116-111c-c111-1118-21c2da97e1cb.snWebCT%2FcobaltMainFrame.dowebct&target=http%3A%2F%2Fvista-server.example.org%3A10080%2Fwebct

9. Test the custom login page before installing it in Vista/CE to ensure it works.
10. Configure Vista/CE to use the custom login page.

    IMPORTANT: Only add this custom page once you are sure that it works, otherwise you could lock yourself and your users out of WebCT.

    1. Log in to Vista/CE as serveradmin.
    2. In the Content Manager tab, click System Files.
    3. Click Get Files and upload your custom login page.
    4. After it is uploaded, click the link to the page to preview it and make a note of the unique content ID that appears in the browser's status bar.
    5. In the Administrationtab, click Utilities > Settings .
    6. Click Branding and set Use the WebCT Login Page to No.
    7. In the Custom Login Page using file content ID box, enter the content ID of the custom login page.
    8. Save the changes and log out.

TroubleShooting

Testing the Shibboleth module in stages (taken from The Powerlinks developers network FAQ)

How do I know whether an authentication module is properly deployed?

1. Does the module show up in server-level SMS, under the "System Integration" Column?

2. Has the deployable component been enabled?

3. Has the "Master Switch" for deployable components been enabled (also in server-level SMS, under the "Deployable Components" settings group)

4. Has the Default SSO Institution been specified?

5. Can you hit your deployable component from a browser, by going to the URL

http://<vista_host_and_port>/webct/urw/ss<url_pattern>.si<ims_id>.sn<ims_name>

Common Error messages in the Shibboleth Identity Provider log: