Shibboleth is an Internet2/MACE project to support inter-institutional sharing of web resources subject to access controls. EZproxy contains built-in support that allows EZproxy to act as a Shibboleth 1.3/2.x/3.x 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 IdP administrator. You may need to install a separate SSL certificate that EZproxy will use when communicating with the IdP to request attribute information. For more information about installing this certificate, see SSL Configuration.
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.
|Discovery Service (DS)
||A Shibboleth 2.x3/x service to allow users to identify the Identity Provider they want to use to authenticate.|
A compact sequence of characters that identifies a specific Shibboleth Identity Provider or Service Provider. An Entity ID may be:
The Entity ID appears in the Metadata EntityDescriptor.
|Identity Provider (IdP)||A service that interacts with users to authenticate their credentials and that provides select information about those users to Service Providers.|
|Metadata||An XML file that contains information on Identity Providers and Service Providers. This file may be the file used for a federations, or it may just contain the information for a single Identify Provider and your EZproxy server. The metadata on any Identity Provider that will be used with EZproxy must also be updated to reflect the information for your EZproxy server.|
|Service Provider (SP)||
A service that redirects unauthenticated users to an Identity Provider and that uses information form an Identity Provider to determine whether or not to provide information to the features of the server.
EZproxy acts as a Service Provider.
|Where Are You From? (WAYF)||A Shibboleth 1.x service to allow suers to identify the Identity Provider they want to use to authenticate.
A file containing an X.509 Certificate used to enable public key cryptography used to:
ShibbolethDisable directive can be used to disable support for a specific version of Shibboleth. Sample use:
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 (\).
||This required parameter specifies the Entity ID for the EZproxy server when using this metadata.|
||This required parameter specifies the file that contains the metadata used to link an EZproxy server to Identity Providers. The default directory for a MetadataFile is the directory where EZproxy is installed.|
||This optional parameter specifies the certificate EZproxy should use when interacting with Identity Providers. This certificate is used when connecting to Identity Providers to retrieve attributes and to decrypt XML signatures and encrypted data from Identity Providers. Certificate numbers can be found on the EZproxy SSL configuration page. In EZproxy 6.2.2 and later, multiple certificate numbers can be supplied in a comma-delimited list.|
|This flag tells EZproxy to sign its AuthnRequest documents before sending them to the IdP. It also changes the metadata displayed by EZproxy in the /shibboleth page so that SPSSODescription element includes AuthnRequestsSigned="true" which also tells the IdP to expect the requests to be signed.|
|See Beta Support for Shibboleth Single Logout|
||This optional parameter specifies the URL from which updated copies of a the MetadataFile can be retrieved. 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.|
||This optional parameter specifies the file containing an X.509 (SSL) certificate that can be used to verify that a MetadataFile retrieved from a MetadataURL is authenticated. The default directory for URLValidateFile is the directory where EZproxy is installed.|
||This optional parameter only applies to Shibboleth 2.1 and specifies an authentication context class reference to include in the authentication request to the Identity Provider. Most institutions will not need to include this value. One possible value for this parameter is urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.|
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. In EZproxy 6.2.2 and later, this page includes an option ("EZproxy Metadata") which displays the complete Shibboleth metadata for the EZproxy server.
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:
||A URL for a Shibboleth 2.x/3.x Discovery Service.|
||An Entity ID used to identify your EZproxy server.|
||An Entity ID used to identify an Identity Provider.|
||A URL to a Shibboleth 1.x Where Are You From (WAYF) service.|
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.x/3.x Identity Provider, use a configuration similar to this in user.txt:
To route users to a Shibboleth 2.x/3.x 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:
ADFS can be used with Shibboleth authentication and EZproxy to provide your users with the ability to use single sign on when accessing EZproxy.
Once you have set up ADFS to work with your Shibboleth authentication, follow the instructions below to create and configure a relying party trust within ADFS for EZproxy.
When creating a relying party trust, some providers will need to access the ADFS metadata in order to complete the assertion. To access the metadata contained within the ADFS instance, visit the following URL:
This URL provides all the metadata necessary that a provider will need to complete a trust. This URL will be the same for any ADFS 2.0 instance.
Follow these steps to create a relying party trust for use with EZproxy on your ADFS server.
EZproxy V6.3 and above provides beta support for Shibboleth Single Logout (SLO). Please note that this feature may require some refinement.
To enable Single Logout (SLO), the option -SLO must be included in the ShibbolethMetadata directive such as:
When this option is included, the metadata for the EZproxy server changes to add entries for SingleLogoutService to specify the URLs at which Identity Providers can communicate with EZproxy to coordinate Single Logout. Since this option changes the metadata, the updated metadata must be provided to the Identity Provider to enable this connection.
In addition, the metadata for the Identity Provider must contain SingleLogoutService entries as well. If it does not, EZproxy will not be able to initiate or respond to a Single Logout request.
When this option is fully enabled, the following actions occur:
The exact page seen by the user after a single logout may be provided by the Identity Provider or by EZproxy. If EZproxy presents the final page, it defaults to sending the contents of the logout.htm file from the docs subdirectory. For installations that have a mixture of Shibboleth and non-Shibboleth authentication, it is possible to create a shiblogout.htm file and place this in the docs subdirectory. If this file exists, it will be sent after single logout completes.
Generating metadata from SSL Certificate page
The SSL Certificate page provides the option to generate the metadata needed for Shibboleth before config.txt has been edited. To support non-SLO and SLO options, this page now includes different links for each of these options.
This page last revised: January 17, 2018