Difference between revisions of "External (Shibboleth) Authentication"
Jump to navigation
Jump to search
(Created page with "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 in...") |
|||
(3 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | This page is the instructions for how to enable Shibboleth authentication system for WeBWorK. |
+ | This page is the instructions for how to enable [http://en.wikipedia.org/wiki/Shibboleth_(Internet2) Shibboleth] authentication system for WeBWorK. |
'''NOTES''': |
'''NOTES''': |
||
Line 5: | Line 5: | ||
* 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. |
* 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. |
* 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== |
==Install Shibboleth== |
||
Line 20: | Line 20: | ||
<li>httpd.conf: The UseCanonicalName directive should be set to On or resource mapping errors will result.</li> |
<li>httpd.conf: The UseCanonicalName directive should be set to On or resource mapping errors will result.</li> |
||
<li>httpd.conf: Ensure that the ServerName directive is properly set, and that Apache is being started with SSL enabled.</li> |
<li>httpd.conf: Ensure that the ServerName directive is properly set, and that Apache is being started with SSL enabled.</li> |
||
− | <li> |
+ | <li>shibboleth2xml: Copy shibboleth2.xml to /etc/shibboleth or change/create the shibboleth2.xml</li> |
<ul> |
<ul> |
||
<li>Under RequestMap, set up host. Your applicationid is not necessary the same as your hostname.</li> |
<li>Under RequestMap, set up host. Your applicationid is not necessary the same as your hostname.</li> |
||
Line 42: | Line 42: | ||
<li>Meta file and attribute map: Copy IdP meta file or/and attribute map into /etc/shibboleth</li> |
<li>Meta file and attribute map: Copy IdP meta file or/and attribute map into /etc/shibboleth</li> |
||
+ | <li>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. |
||
+ | <pre> |
||
+ | ... |
||
+ | <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/> |
||
+ | ... |
||
+ | </pre> |
||
<li>webwork.apache2-config: exempt Shibboleth from being handled by Appache::WeBWork in line 148</li> |
<li>webwork.apache2-config: exempt Shibboleth from being handled by Appache::WeBWork in line 148</li> |
||
<pre> |
<pre> |
||
Line 53: | Line 59: | ||
<li>shib.conf: Apache Shibboleth configuration. Add the following directive</li> |
<li>shib.conf: Apache Shibboleth configuration. Add the following directive</li> |
||
<pre> |
<pre> |
||
− | <LocationMatch ^/[^webwork2_files|^webwork2_course_files]> |
||
+ | # allows anonymous course selection, but requires authentication from then on |
||
+ | <LocationMatch ^/webwork2/.+> |
||
AuthType shibboleth |
AuthType shibboleth |
||
ShibRequestSetting requireSession 1 |
ShibRequestSetting requireSession 1 |
||
Line 60: | Line 67: | ||
</pre> |
</pre> |
||
− | <li>global.conf: webwork main configuration file |
+ | <li>global.conf: webwork main configuration file (or localOverride.conf for newer version of WeBWorK):</li> |
+ | Change/Add the following to enable shibboleth authentication: |
||
<pre> |
<pre> |
||
+ | $authen{user_module} = { |
||
+ | "*" => "WeBWorK::Authen::Shibboleth", |
||
+ | }; |
||
+ | </pre> |
||
+ | |||
+ | Add the following lines at the bottom and change the Shibboleth handler accordingly. |
||
+ | <pre> |
||
+ | $shibboleth{login_script} = "/Shibboleth.sso/Login"; |
||
$shibboleth{logout_script} = "/Shibboleth.sso/Logout?return=".$server_root_url.$webwork_url; |
$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{session_header} = "Shib-Session-ID"; # the header to identify if there is an existing shibboleth session |
||
Line 67: | Line 82: | ||
$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_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 |
$shibboleth{hash_user_id_salt} = ""; # salt for hash function |
||
− | #define mapping between shib and webwork |
+ | # 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'; |
||
</pre> |
</pre> |
||
</ul> |
</ul> |
||
Line 82: | Line 97: | ||
</pre> |
</pre> |
||
</ol> |
</ol> |
||
+ | |||
+ | == Credits == |
||
+ | |||
+ | Pan Luo[mailto:webwork.support@ubc.ca] (Centre for Teaching, Learning and Technology, University of British Columbia) wrote the WeBWorK::Authen::Shibboleth module, based on existing [[External (Cosign) Authentication|Cosign WeBWorK authentication module]]. |
||
+ | |||
+ | [[Category:Administrators]] |
Latest revision as of 16:21, 29 November 2022
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
- Install Shibboleth from repo
- 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.
- Change the ApplicationDefault or ApplicationOverride
- 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
- shib.conf: Apache Shibboleth configuration. Add the following directive
- global.conf: webwork main configuration file (or localOverride.conf for newer version of WeBWorK): Change/Add the following to enable shibboleth authentication:
- Start Shib
- Restart Apache
cd /etc/yum.repos.d/ sudo wget http://download.opensuse.org/repositories/security://shibboleth/RHEL_5/security:shibboleth.repo sudo yum install shibboleth
<Host name="YOUR_WEBWORK_HOSTNAME" applicationId="YOUR_WEBWORK_HOSTNAME" authType="shibboleth" requireSession="true" exportAssertion="false" redirectToSSL="443"> </Host>
<ApplicationOverride id="YOUR_HOSTNAME" entityID="https://YOUR_HOSTNAME/shibboleth-sp" homeURL="YOUR_WEBWORK_HOME_URL" REMOTE_USER="eppn" />
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 }
# allows anonymous course selection, but requires authentication from then on <LocationMatch ^/webwork2/.+> AuthType shibboleth ShibRequestSetting requireSession 1 require valid-user </LocationMatch>
$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';
sudo /sbin/service shibd start
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.