Using Shibboleth instead of LDAP to authenticate Ezproxy users

EZProxy supports Shibboleth based access in place of traditional username/password authentication using LDAP or another user repository. The Shibboleth approach adds the potential to use Single-Sign-On, removing the need for users to enter usernames and passwords if they have already done so when accessing other Shibboleth protected services such as campus email or any of the services within the Edugate federation.
This guide provides details on how an existing EZProxy deployemnt can be configured to use EZproxy with Shibboleth in the Edugate federation, but it could also be used as an guide for using Shibboleth with EZproxy without the use of Edugate by using the campus Shibboleth Identity Provider (IdP) service bilaterally.

EZProxy Configuration

• Create a Self-Signed Certificate
  • Open the EZproxy Administration page and select Manage SSL (https) certificates, then select the Create new SSL certificatelink. Complete the form with values relevant to your library, here are suggested values;
    • Key size: 2048
    • Country: IE
    • State or Province (optional):
    • City or Locality (optional): Mullingar
    • Organization: Mullingar Institute of Technology
    • Organization Unit (optional): MIT Library
  • Select radio box that lists the hostname of your EZproxy server e.g. ezproxy.mit.ie (do not select the wildcard option *.mit.ie).
  • Finally, select the Create Self-Signed certifiate option. On the next screen, do not type ACTIVE in the dialogue box when prompted. Return to the Manage SSL (https) certificates page and take note of the ID number assigned to your new certificate.
• The next step configures EZProxy to act as a SAML Service Provider so that Shibboleth Identity Providers can exchange SAML authentication messages with EZproxy.
• Open the EZproxy configuration file config.txt Add the following directives below which are explained hereafter

ShibbolethDisable 1.3
ShibbolethMetadata \
   -EntityID=http://ezproxy.mit.ie/ezp \
   -File=edugate-metadata-unsigned.xml \
   -Cert=1
   -URL=https://edugate.heanet.ie/edugate-metadata-unsigned.xml

1.  ShibbolethDisable 1.3 Disables the older 1.3 version of Shibboleth and forces EZProxy to use the newer version of SAML protocol (SAML2)
2. EntityID is a URL that uniquely identifies your EZProxy SAML service, the URL does not have to resolve to any particular content. Later in this guide, your institutions Shibboleth Identity provider will use this identifier value when communicating with EZproxy.
3. File This file contains the locally cached copy of the Edugate metadata. The file must be manually downloaded once and placed in the main EZproxy directory (e.g. /usr/local/ezproxy)
4. URL This URL contains the metadata of all participating services and identity providers in the Edugate federation, most importantly it contains the metadata of your institutions identity provider service.
5. Cert This is the ID number of the certificate you created in the previous steps. 

• At this point EZProxy should be restarted, once restarted the EZproxy administration page will contain a new link titled Manage Shibboleth. Open the Shibboleth management page and click on Certificate Metadata. The content that appears can be used to register your EZProxy SAML Service Provider within the Edugate Resource Registry the content of the file can also be sent within and an email to the HEAnet Network Operations Center at noc@heanet.ie requesting that your EZProxy SAML Service Provider is registered within Edugate (include the entityID you chose in the earlier steps).
• Once your registration has been approved, you can proceed; open the Manage Shibboleth page, select your institution from the list that appears beside the Show 2.0 Attributes from this Identity Provide button and then press the button. This will test parially test your Shibboleth integration by taking you to your institutions login page (do not enter credentials yet).\
• Edit the user.txt file and add the following stanza with your IdP's entityID (e.g. http://idp.mit.ie/idp/shibboelth)

::Shibboleth
IDP20 \ http://idp.mit.ie/idp/shibboleth
/Shibboleth

• Open the login.html page from the ezproxy docs directory and amend the html as follows

<form action="/login" method="post">
<input type="hidden" name="url" value="^U" />
<input type="submit" name="auth" value="shibboleth" />
</form>

(The above html should be added above the closing body and html tags at the bottom of the html file)

• Create a shibuser.txt file and deny access to alumni (using eduPersonAffiliation) and provide specific users (using eduPersonPrincipalName) with ezproxy admin priviliges using the following template rule;

If (Any(auth:urn:oid:1.3.6.1.4.1.5923.1.1.1.1, "alumni"));
Deny alum.html
If auth:urn:oid:1.3.6.1.4.1.5923.1.1.1.6 eq "jbloggs@mit.ie";
admin

You should now be able to login to ezproxy using Shibboleth (ensure your IdP releases the eduPersonPrincipalName and eduPersonAffiliation attributes).