Note that the SDSS Federation no longer accepts new applications to join. Applications should instead be made to join the UK Federation. The information on this page is of historical interest only.
Shibbolizing an EDINA Service
At present, this page applies only to services based on Edina::Autho::LoginScript and SiteSearch, and hosted on bodach (the setup on nevis is different). It is intended for EDINA in-house use.
The Front Page
Most EDINA services have a "front page" with current service status information and a "login" button, which initiates an Athens login.
What we've done so far for Shibbolized services is to create a similar front page but with two login buttons: one for Shibboleth and one for Athens. See, for example:
If or when Eduserv build an Athens to Shibboleth gateway that acts as a Shibboleth identity provider within the SDSS federation, the Athens button could be dropped, because users would be able to select this Athens IdP during the Shibboleth login process.
The Shibbolized front page is hosted by the main EDINA web server in the usual way. The HTML file for the EIG example above lives in /home/eudlweb/edina/eig/shibb.shtml. This is based on the standard index.shtml, modified as follows:
1. The display.login.prompt.cgi server-side include script usually used to generate the Athens login button is modified:
<!-- Start include login prompt --> <!--#include virtual="/cgi/display.login.prompt.cgi?service=eig&login=shibbprompt" --> <!-- End include login prompt -->
The &login=shibbprompt argument inserts the file /home/eudlweb/edina.autho/eig/shibbprompt.html into the generated output. This file contains code to generate the Athens login button as usual but also a Shibboleth login button:
<tr>
<td width="10%">
<form action="http://<!--SERVICE-->.sdss.ac.uk/<!--SERVICE-->login-sso">
<input id="Shib" type="image"
src="/images/button_login.gif"
title="login Shibboleth user"/>
<input type="hidden" name="logout_url"
value="http://edina.ac.uk/eig/shibb.shtml">
</form>
</td>
<td class="subtext"> using Shibboleth</td>
</tr>
The explicit logout_url is required because on logout we want the user to be returned to the modified login page (with the Shibboleth button) rather than the default service login page (without).
display.login.prompt.cgi maps <!--SERVICE--> to the service= argument it was given, in this case eig, so the generated button invokes the script http://eig.sdss.ac.uk/eiglogin-sso.
This action URL is not hosted by the main EDINA web server. The eig.sdss.ac.uk domain is hosted by a separate, Shibboleth-enabled copy of Apache running from the shibb user, which allows the action URL to be Shibboleth protected.
The Login Script
The Shibboleth login script is usually the same file as an existing Athens SSO login script. The script must be modified so that it contains no Athens or Shibboleth-specific code (this is described below). File permissions must also be set to make the script accessible to both the Athens and Shibboleth web servers. Taking the EIG script as an example:
cd /home/oclc/service/eig/cgi-bin/edina chmod o+rx eiglogin-sso
When you want a login script to be Shibboleth-enabled, you must contact the SDSS team and ask for the shibb Apache configuration to be modified so that the appropriate Shibboleth-protected sdss.ac.uk script URL (in this case http://eig.sdss.ac.uk/eiglogin-sso) can be set up to refer to the script file. The file must therefore be both readable and executable by the shibb user. General permission is given to the login script (chmod o+rx) rather than using a specific ACL to grant access only to shibb, because ACLs don't seem to mix well with Apache and the way symbolic links are heavily used in the paths to the service cgi-bin directories. In addition to giving read and execute permissions to the script file itself, as shown above, every directory along the path to the script file must also be traversable by the shibb user (by applying chmod o+x), including any directories hidden within symbolic links. See also File Permission Issues later.
Scripts not explicitly made accessible to the shibb user in this way cannot be accessed via Shibboleth.
The simplest login script would be something like this:
#!/home/cpan/bin/perl
use lib (getpwnam('sdadmin'))[7].'/perlib';
use Edina::Autho::LoginScript;
package Edina::Autho::LoginScript;
$SiteSearch = 1;
service("eig", "<start-url>");
Scripts that test for more than one resource use a variant form of the service() call, e.g., for EMOL:
service([media, mediamedical], "<start-url>");
An array of EDINA short-form service names is used in this case (rather than Athens or Shibboleth-specific features).
In practice, scripts often do test multiple resources. For example, the EMOL script does so to check whether a user is authorised for restricted medical content, by overriding the default authorise() function. The authorise() function will be called automatically from the LoginScript framework code. If it returns normally, the user is granted access. To deny access, the function should simply "exit;", in which case it will usually redirect the user to an HTML error page (by printing a suitable redirect header line) before exiting.
sub authorise {
$restricted = authorised("media");
$fullservice = authorised("mediamedical");
if($fullservice) {
# Medical allowed
...
}
...
}
The authorised() function used in the example above takes an EDINA short service name as its argument and returns a Boolean value, which is true if the user is authorised to access the named service. The same function works with either Athens or Shibboleth. Code that will not work in both environments should be avoided or, if essential, made conditional on one of the Boolean variables below.
Some public variables are set for use by the script code:
- $athens
- Boolean: script has been invoked by an Athens login; it is safe to execute Athens-dependent code.
- $institution_code
- Athens-style institution code (e.g., "edi") if known (from inst-codes file, see below). This is used for OpenURL support in Shibboleth mode. May be undef if no mapping is given for the user's Shibboleth domain in the inst-codes file or if the script was invoked via Athens.
- $shibboleth
- Boolean: script has been invoked by a Shibboleth login; it is safe to execute Shibboleth-dependent code.
Some of the usual LoginScript variables are also set, even when invoked by Shibboleth:
- $username
- If the eduPersonTargetedID attribute is present, $username is based on its value, a base64 string like JK5jhuMPbKBNlllh4DLlqb9nLXM=@sdss.ac.uk (with any '/'s in the base64 part replaced by '%'s to allow use as a filename if required). Otherwise, $username is set to '_shibboleth'. The targeted ID is an opaque handle for an individual user, which is persistent over multiple logins (to allow for service personalisation). Only the identity provider (origin institution) can work back from the targeted ID to an individual's real identity.
- $personal_account
- If eduPersonTargetedID is present then 1, else 0.
For more complex authorisation decisions, Shibboleth environmental variables like $ENV{HTTP_SHIB_EP_AFFILIATION} or $ENV{HTTP_SHIB_TARGETEDID} can be inspected directly.
[#permissions]
File Permission Issues
The web server running the login script runs as the shibb user but the <service>-use.log files are owned by oclc. The service log files must thefefore be explicitly made writable by the shibb user. Taking EIG as an example:
cd /home/oclc/service/logs setfacl -m user:shibb:rw-,mask:rw- eig-use.log
Similarly, the login script must be made readable and executable by Apache running under the shibb user:
cd /home/oclc/service/eig/cgi-bin/edina setfacl -m user:shibb:r-x,mask:r-x eiglogin-sso
If you are feeling more relaxed, you could make it readable and executable by anyone, instead of just shibb:
chmod a+rx eiglogin-sso
Additionally, to allow the shibb Apache to traverse the path to the login script and the log files, the 'x' bit must be set on every directory on the path from /home/oclc to the directories containing those files, including any directories hidden inside symbolic links:
chmod a+x <directory>
Some other common files owned by the oclc user that are required by most service login scripts have also been made accessible to the shibb user for use by Shib login scripts, and the directories containing those files have been made traversable by anyone. This only needs to be done once, so the following appears as a matter of record only.
cd /home/oclc/service/conf setfacl -m user:shibb:r--,mask:r-- services.ini cd /home/oclc/service chmod o+x conf chmod o+x logs cd /home/oclc chmod o+x service
SDSS Team Actions
When a new Shibboleth login script is needed, the SDSS team must be contacted and asked to modify the shibb Apache configuration to map the URL http://<service>.sdss.ac.uk/<script> to the actual location of the file.
For reference, the modifications required to /home/shibb/shibb12/apache/conf/httpd.conf (in the appropriate <VirtualHost>) look like this:
ServerName emol.sdss.ac.uk DocumentRoot /home/eucs/oclc/service/emol/cgi-bin ScriptAlias /emollogin-sso /home/eucs/oclc/service/emol/cgi-bin/emollogin-sso <Files emollogin-sso> Options +ExecCGI AuthType shibboleth ShibRequireSession On require valid-user </Location>
Note that the copy of Apache in the shibb user must be started or stopped using wwwctl rather than apachectl, for example:
/home/shibb/shibb12/apache/bin/wwwctl restart
The SDSS team should add a description of the way the new service uses Shibboleth attributes to the AttributeUsage page.
In addition to modifying the Apache configuration and the attribute directory, the SDSS team must modify the institutional rights file, described in the next section.
Institutional Rights File
The SDSS team should inspect the institutional rights file, /home/shibb/inst-access, and ensure that all institutions that are subscribed to the service being Shibbolized and are also members of the SDSS federation are listed there. The format is line-oriented and may include comments introduced by the '#' character:
lse.ac.uk: media sdss.ac.uk: media eig
This says that the Shibboleth scopes (domains) lse.ac.uk and sdss.ac.uk both have rights to use the "media" service (EMOL) but sdss.ac.uk can also use "eig" (these are standard EDINA short-form service names).
Institutional Codes File
The mechanisms used to generate OpenURLs and EDINA weblinks currently depend on old-style Athens 3-letter "institutional codes", e.g., "edi" for EDINA. An additional file, /home/shibb/inst-codes, defines a mapping from Shibboleth domains to these codes. Again, this is a simple line-oriented file of domain:code pairs with '#' comments, for example:
sdss.ac.uk: edi
At present, an exhaustive list of every domain in the federation is not required. OpenURLs and weblinks are simply not generated if the user's Shibboleth domain is not listed in this file.