External (Shibboleth) Authentication

This page is the instructions for how to enable Shibboleth authentication system for WeBWorK.

NOTES:

• The installation is based on Redhat Enterprise Linux 5.7. The installation for your distribution may vary. Please see the installation guide from Shibboleth website.
• The shibboleth2.xml is generated by UBC IT shibboleth Configuration generation form. If you use the one distributed with Shibboleth SP, you will need to modified to fit your environment.
• WeBWorK is configured on web root, instead of /webwork2. If your webwork is under a path, you will need to modified the shibboleth protection regular expression in shib.conf step 2.
• At the time of writing, there were breaking changes to Shibboleth after webwork v2.14. See https://github.com/openwebwork/webwork2/issues/1844 details.

Install Shibboleth

1. Install Shibboleth from repo

cd /etc/yum.repos.d/
sudo wget http://download.opensuse.org/repositories/security://shibboleth/RHEL_5/security:shibboleth.repo
sudo yum install shibboleth

2. Change configuration
• httpd.conf: The UseCanonicalName directive should be set to On or resource mapping errors will result.
• httpd.conf: Ensure that the ServerName directive is properly set, and that Apache is being started with SSL enabled.
• shibboleth2xml: Copy shibboleth2.xml to /etc/shibboleth or change/create the shibboleth2.xml
• Under RequestMap, set up host. Your applicationid is not necessary the same as your hostname.

 <Host name="YOUR_WEBWORK_HOSTNAME" 
                  applicationId="YOUR_WEBWORK_HOSTNAME"  
                  authType="shibboleth" 
                  requireSession="true" 
                  exportAssertion="false"
                  redirectToSSL="443">
</Host>

• Change the ApplicationDefault or ApplicationOverride

<ApplicationOverride id="YOUR_HOSTNAME"
                             entityID="https://YOUR_HOSTNAME/shibboleth-sp"
                             homeURL="YOUR_WEBWORK_HOME_URL"
                             REMOTE_USER="eppn" />

• Meta file and attribute map: Copy IdP meta file or/and attribute map into /etc/shibboleth
• Be sure to extract an attribute suitable for a username within attribute-map.xml. A few eduPerson attributes, including eppn, are extracted by default. If your identity provider releases a uid attribute, then you'll need to extract that by adding/uncommenting that mapping. eduPersonPrincipalName (eppn), uid, persistant-id are common options.

  ...
  <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
  ...
  

• webwork.apache2-config: exempt Shibboleth from being handled by Appache::WeBWork in line 148

if ($webwork_url eq "/") {
        $Location{$webwork_courses_url} = { SetHandler => "none" };
        $Location{$webwork_htdocs_url} = { SetHandler => "none" };
        $Location{"/Shibboleth.sso"} = { SetHandler => "none" }; # add this
        $Location{"/shibboleth-sp"} = { SetHandler => "none" };  # add this
}

• shib.conf: Apache Shibboleth configuration. Add the following directive

# allows anonymous course selection, but requires authentication from then on 
<LocationMatch ^/webwork2/.+>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</LocationMatch>

• global.conf: webwork main configuration file (or localOverride.conf for newer version of WeBWorK):
Change/Add the following to enable shibboleth authentication:

$authen{user_module} = {
       "*" => "WeBWorK::Authen::Shibboleth",
};

Add the following lines at the bottom and change the Shibboleth handler accordingly.

$shibboleth{login_script} = "/Shibboleth.sso/Login";
$shibboleth{logout_script} = "/Shibboleth.sso/Logout?return=".$server_root_url.$webwork_url;
$shibboleth{session_header} = "Shib-Session-ID"; # the header to identify if there is an existing shibboleth session
$shibboleth{manage_session_timeout} = 1; # allow shib to manage session time instead of webwork
$shibboleth{hash_user_id_method} = "MD5"; # possible values none, MD5. Use it when you want to hide real user_ids from showing in url. 
$shibboleth{hash_user_id_salt} = ""; # salt for hash function
# define mapping between shib and webwork
# use the id value of one of attributes being provided/extracted in shibboleth/attribute-map.xml
# eppn, uid, persistant-id are common choices
#$shibboleth{mapping}{user_id} = 'eppn'; 
$shibboleth{mapping}{user_id} = 'uid';

3. Start Shib

sudo /sbin/service shibd start

4. Restart Apache

sudo /sbin/service httpd restart

Credits

Pan Luo[1] (Centre for Teaching, Learning and Technology, University of British Columbia) wrote the WeBWorK::Authen::Shibboleth module, based on existing Cosign WeBWorK authentication module.