The options described in this document require EZproxy 3.4a GA (2005-08-02) or later.
Shibboleth is an Internet2/MACE project to support inter-institutional sharing of web resources subject to access controls. 1 EZproxy 3.4a contains built-in support to support that allows EZproxy to act as a Service Provider (SP), allowing EZproxy to accept user authentication and authorization information from your institution's Identity Provider (IdP) and to map that information into corresponding EZproxy authorizations.
Configuring EZproxy for Shibboleth requires careful coordination with your Identity Provider (IdP) administrator. You may need to install a separate SSL certificate that EZproxy will use when communicating with the IdP to request attribute information. See SSL Configuration for information on SSL configuration and Technical Notes for technical notes on how to import existing certificates into EZproxy.
The AssertionConsumerServiceURL, also know as the shireURL, for an EZproxy server is the server's https name followed by /Shibboleth.shire. As an example, for a server with an https name of https://ezproxy.yourlib.org, this URL is:
This URL does not need to appear anywhere in the EZproxy configuration files, but is needed when configuring your Identity Provider.
The following directives are used in config.txt/ezproxy.cfg to link EZproxy to your Shibboleth federation.
ShibbolethSites File= IQ-sites.xml URL= https://wayf.internet2.edu/InQueue/IQ-sites.xml AACert= 2
ShibbolethSites File= localhost-sites.xml
This directive provides the URL of your Shibboleth WAYF (Where Are You From) service. This directive may only appear once.
This directive provides the string that EZproxy should includes as its providerId parameter when redirecting users to the WAYF service. This value is typically assigned by your federation. This directive may only appear once.
This directive points to federation metadata. It may appear more than once. It accepts several parameters, with the file parameter required and all others optional. EZproxy 4.0f GA (2006-12-10) can use either 1.2 or 1.3 metadata, whereas earlier releases only understand 1.2 metadata.
Once you add these directives to config.txt/ezproxy.cfg and restart EZproxy, you should access the EZproxy administration page where you will find an option to Manage Shibboleth. In the Manage Shibboleth page, there is a link to display release attributes. You will use this link to verify basic Shibboleth functionality.
If you want to mix traditional EZproxy authentication options with Shibboleth, edit the login.htm file and add a link similar to this:
<a href="^W">Login with Shibboleth</>
Users who want to login with Shibboleth will click this link, whereas other users will use the login form.
If you want to redirect all authentication handling to Shibboleth, editing user.txt/ezproxy.usr and add the line:
If you use this option, the EZproxy login form is disabled and all users are redirected to the WAYF instead.
This file is used to map Shibboleth attributes to EZproxy authorizations. This sample demonstrates how to restrict access to a specific Identity Provider, block alumni, place employees into an additional EZproxy group, place people affiliated with the law.example.edu scope into an additional EZproxy group, designate a specific user as an EZproxy administrator, and map an attribute for EZproxy to use as the username for logging, enforcing transfer limits, etc.
Test -Not -Site urn:mace:inqueue:example.edu; Deny unaffiliated.html
Test urn:mace:dir:attribute-def:eduPersonPrimaryAffiliation alum; Deny alum.html
Test urn:mace:dir:attribute-def:eduPersonAffiliation employee; Group +Employee
Test urn:mace:dir:attribute-def:eduPersonScopedAffiliation -scope law.example.edu -re .*; Group +Law
Test urn:mace:dir:attribute-def:eduPersonPrincipalName -scope example.edu ezmgr; Admin