External (Shibboleth) Authentication

From WeBWorK
Jump to: navigation, search

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


  • 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.

Install Shibboleth

  1. Install Shibboleth from repo
  2. cd /etc/yum.repos.d/
    sudo wget http://download.opensuse.org/repositories/security://shibboleth/RHEL_5/security:shibboleth.repo
    sudo yum install shibboleth
  3. 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" 
      • Change the ApplicationDefault or ApplicationOverride
      • <ApplicationOverride id="YOUR_HOSTNAME"
                                     REMOTE_USER="eppn" />
    • Meta file and attribute map: Copy IdP meta file or/and attribute map into /etc/shibboleth
    • 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
    • <LocationMatch ^/[^webwork2_files|^webwork2_course_files]>
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        require valid-user
    • 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
      $shibboleth{mapping}{user_id} = 'puid';
  4. Start Shib
  5. sudo /sbin/service shibd start
  6. Restart Apache
  7. sudo /sbin/service httpd restart


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.

follow us