The features described in this document require EZproxy 5.1b GA or later.
EZproxy 5.1a introduced this support, but contains a flaw that prevents the proper group handling. If your institution uses groups with Shibboleth, you are encouraged to upgrade to a later release.
Shibboleth is an Internet2/MACE project to support inter-institutional sharing of web resources subject to access controls. 1 EZproxy 5.1 contains built-in support to support that allows EZproxy to act as a Shibboleth 1.3/2.1 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.
Earlier versions of EZproxy supported Shibboleth 1.2. This earlier version is still supported, although it is not recommended for new installations. See original Shibboleth 1.2 support for information on this earlier version.
The following is a list of terms used in this document. The definitions of these terms have been simplified to address only how they relate to configuring EZproxy for use with Shibboleth. For more complete definitions, please refer to the Shibboleth Project.
The ShibbolethDisable directive can be used to disable support for a specific version of Shibboleth. Sample use:
The ShibbolethMetadata directive is used in config.txt to link EZproxy to your Shibboleth Identity Providers. This directive may appear multiple times to link EZproxy to multiple federations.
Optional values are shown in square brackets. The entire ShibbolethMetadata directive with all options can appear on a single line or it can broken across multiple lines as shown. When breaking options across multiple lines, all but the last such line must end with a space followed by a backslash (\).
Once you add this directive to config.txt 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.
There are a number of different options for routing users to your Identity Provider for authentication. The examples of these options employ the following abbreviations:
To route users to a specific Shibboleth 1.3 Identity Provider, use a configuration similar to this in user.txt:
To route users to a Shibboleth 1.3 WAYF, use a configuration similar to this in user.txt:
WAYF13 -EntityID=EZproxyEntityiD WAYFURL
If all of your ShibbolethMetadata directives use the same -EntityID, then you can use the first form of WAYF13. If you have multiple ShibbolethMetadata directives with varying -EntityID values, you must use the second form and explicitly specify the EntityID of your EZproxy server for the specific WAYF.
To route users to a specific Shibboleth 2.1 Identity Provider, use a configuration similar to this in user.txt:
To route users to a Shibboleth 2.1 Discovery Service, use a configuration similar to this in user.txt:
DS20 -EntityID=EZproxyEntityID DSURL
If all of your ShibbolethMetadata directives use the same -EntityID, then you can use the first form of DS20. If you have multiple ShibbolethMetadata directives with varying -EntityID values, you must use the second form and explicitly specify the EntityID of your EZproxy server for the specific Discovery Service.
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="/login?auth=shibboleth&url=^U">Login with Shibboleth</a>
and then modify user.txt to be similar to this:
If login:auth eq "shibboleth"; IDP20 IDPEntityID
If login:auth eq "shibboleth";
in front of whichever Shibboleth routing method you use.
Users who want to login with Shibboleth will click this special link, whereas other users will use the login form.
This file allows the use of Shibboleth attributes to make EZproxy authorization decisions. 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.
If !(auth:issuer eq "https://idp.yourlib.org/shibboleth/idp");
If auth:urn:mace:dir:attribute-def:eduPersonPrimaryAffiliation eq "alum";
If Any(auth:urn:mace:dir:attribute-def:eduPersonAffiliation, "employee");
If Count(auth:urn:mace:dir:attribute-def:eduPersonScopedAffiliation@law.example.edu) > 0;
If auth:urn:mace:dir:attribute-def:eduPersonPrincipalName@example.edu eq "ezmgr";
Set login:loguser = auth:urn:mace:dir:attribute-def:eduPersonTargetedID
To determine the attributes that are available for use, access the EZproxy administration page, then the Manage Shibboleth page, and use one of the options provided to display your attributes. Note that auth: is placed in front of the attribute name that appears on this page. For the attribute name, if both a name and a friendly name appear, you can use either after auth:. If a value appears in the scope column, then an @ sign and this scope value must be added to the end of the attribute name.
This step only applies for EZproxy servers using proxy by hostname with a wildcard certificate (e.g., *.ezproxy.yourlib.org). If this does not apply, skip to the next step.
Other Shibboleth servers may not be willing to use a wildcard certificate for communication. If necessary, you can create an additional, separate certificate named login. followed by your EZproxy server name (e.g., login.ezproxy.yourlib.org) which will be used just for communication with other Shibboleth servers. To create such a certificate, access the EZproxy administration page, and from there choose Manage Shibboleth, and from there choose Create New SSL Certificate for Shibboleth Communication, and then proceed to complete the information for the certificate. Depending on the certificate authority used in your network, you may need to coordinate this step with the person who manages your certificates.
From SSL configuration, click on the certificate you will use, and from the certificate page, click View Shibboleth metadata for this certificate. You will need to provide this information to the person who manages your metadata.
NOTE: The first tag in the metadata is the EntityDescriptor tag. This tag must contain an entityID attribute to be complete. This attribute must be manually added to the metadata, requiring the first line to be changed from:
to something like this:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID=" your-entity-id-here">
Edit config.txt and change your ShibbolethMetadata directives to reflect your actual EZproxyEntityID, MetadataFile, and EZproxyCertNumber, such as:
If you have a URL to download the metadata, include this as well, such as:
If you also have a file with a certificate to validate the data retrieved from the URL, incorporate that, such as: