Documentation

Shibboleth

Shibboleth is the software powering the Central KU Leuven Login. It's a piece of software used by many universities to supply identification and access management.

ULYSSIS works together with ICTS to supply limited access to Shibboleth. We are however only able to supply Shibboleth to those approved by ICTS. In practice all faculty unions will be granted access if they can prove they have the technical ability to use Shibboleth in a safe and privacy friendly way. For other organisations it can be more difficult to get access, therefore it is best to write an extensive explenation of what you plan to do with Shibboleth, why your organisation requires it, what your organisation does, and other relevant information. We will then contact ICTS with your request.

How to request

To request Shibboleth access, you first need to make sure the domain you wish to use Shibboleth on has valid SSL certificates. Lately ICTS has been pushing that all traffic to the website is already over HTTPS before Shibboleth is issued. For more info you can check Getting SSL

If you have SSL set up you need to send an email to request Shibboleth to ulyssis@ulyssis.org. The email must contain the following info:

  • What domain you wish to use Shibboleth on (this must be a single domain, so keep subdomains and www in mind)
  • What you will be using Shibboleth for and in general what your application will do. This explenation is required by ICTS. If you fail to convince them they will not grant your domain access.
  • What attributes you wish to use and what you will do with them (and whether you will store them). You can find the list of attributes on https://admin.kuleuven.be/icts/services/aai/attributes
  • Explicitly state you grant ULYSSIS permission to edit the .htacccess file to be able to export the required Shibboleth Metadata
  • If you are not a recognised faculty union you will need to include an extra motivation why you require Shibboleth (as noted above)

If your application is complete and correct we will file a formal request. We will of course notify you of ICTS' response.

Deploying Shibboleth

After you have been granted access you can soon start using Shibboleth.

The first step is to add the following lines to your .htaccess

ShibDisable Off
AuthType Shibboleth
require shibboleth
ShibRequireSession off

We disable certain features of Shibboleth here because it will otherwise interfere with any other HTTP-auth options you might be using.

Now that you have added this information to .htaccess you are able to serve requests to Shibboleth.sso, if your request is well-formed the sso will handle communication with the IdP (identity provider) of the KU Leuven. A login link follows the following syntax:

https://[YOUR_HOSTNAME]/Shibboleth.sso/WAYF/kuleuven?target=[URLENCODED_RETURN_URL]

And logout links:

https://[YOUR_HOSTNAME]/Shibboleth.sso/Logout?return=[URLENCODED_DISPLAY_URL]

It is important to note that on logout the user will stay on the KU Leuven's IdP-page and your link will only be displayed. The user will NOT be redirected (even though this is the normale behaviour according to the Shibboleth documentation).

As soon as a user is logged in, his or hers attributes will be available to your application. Attributes are certain properties that an account may have and that supply further information about them. Some examples are: first name, last name, mail, student id. All of these will be available as HTTP headers. But keep in mind that apache might prefix those with REDIRECT_ multiple times (for example when mod_rewrite is used). For an overview of all attributes you can check out http://shib.kuleuven.be/secure/allAttributes

More general information on the KU Leuvens implementation can be found on http://shib.kuleuven.be/ . But be aware of the fact that some of the documentation is very outdated (Most notably information about shib 1.3)