External (Shibboleth) Authentication

Outdated

IMPORTANT: The content of this page is outdated. Do not rely on the information contained in this page.

Shibboleth authentication is still supported in WeBWorK, but these instructions are out of date. For WeBWorK 2.19 you should consult the conf/authen_shibboleth.conf.dist file for more recent information about configuring 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.