Shibboleth Authentication
Minimum version required
The options described in this document require EZproxy 3.4a GA (2005-08-02) or later.
Overview
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.
AssertionConsumerServiceURL (shireURL)
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:
https://ezproxy.yourlib.org/Shibboleth.shire This URL does not need to appear anywhere in the EZproxy configuration files, but is needed when configuring your Identity Provider.
config.txt/ezproxy.cfg directives
The following directives are used in config.txt/ezproxy.cfg to link EZproxy to your Shibboleth federation.
ShibbolethWAYF https://wayf.internet2.edu/InQueue/WAYF
ShibbolethProviderId https://ezproxy.yourlib.org/shibboleth
ShibbolethSites File= IQ-sites.xml URL= https://wayf.internet2.edu/InQueue/IQ-sites.xml AACert= 2
ShibbolethSites File= localhost-sites.xml
ShibbolethWAYF
This directive provides the URL of your Shibboleth WAYF (Where Are You From) service. This directive may only appear once.
ShibbolethProviderId
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.
ShibbolethSites
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.
- File= IQ-sites.xml
- This parameter provides the filename that contains metadata for this site. This parameter is required.
- URL= https://wayf.internet2.edu/InQueue/IQ-sites.xml
- When the URL parameter is provided, EZproxy will attempt to retrieve the specified URL at startup and every 24 hours thereafter. If it successfully accesses the URL and the contents are valid, it overwrites the file specified with File with the retrieved contents and sets the contents as the active metadata for the site.
- AACert= 2
- This parameter indicates which certificate EZproxy should use when connecting to the Attribute Authority (AA) of any Identity Provider in this site. Certificate numbers can be found on the EZproxy SSL configuration page.
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.
Routing users to Shibboleth for authentication
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:
::WAYF If you use this option, the EZproxy login form is disabled and all users are redirected to the WAYF instead.
shib.usr
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
Group Default
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
MapUser urn:mace:dir:attribute-def:eduPersonTargetedID