Shibboleth Authentication

Minimum version required

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.

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, this URL is:

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.

ShibbolethSites File= IQ-sites.xml URL= 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.

File= IQ-sites.xml
This parameter provides the filename that contains metadata for this site. This parameter is required.
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:


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 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; 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 -re .*; Group +Law
Test urn:mace:dir:attribute-def:eduPersonPrincipalName -scope ezmgr; Admin
MapUser urn:mace:dir:attribute-def:eduPersonTargetedID