Shibboleth 1.3/2.1 Authentication

Minimum version required

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.

Overview

Shibboleth is an Internet2/MACE project to support inter-institutional sharing of web resources subject to access controls. ¹ 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.

Original Shibboleth 1.2 support

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.

Terms

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.1 service to allow users to identify the Identity Provider they want to use to authenticate.
Entity ID: A compact sequence of characters that identifies a specific Shibboleth Identity Provider or Service Provider. An Entity ID may be a Uniform Resource Locator (URL) such as https://shibboleth.yourlib.org/sp or a Uniform Resource Name (URN) such as urn:mace:yourfederation:yourlib. 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 federation, or it may just contain the information for a single Identity 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 from 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 users to identify the Identity Provider they want to use to authenticate.
X.509 Certificate: A file containing an X.509 Certificate used to enable public key cryptography used to (1) sign and encrypt data for use with Shibboleth and (2) authenticate server-to-server connections when using Secure Socket Layer (SSL) communication.

config.txt directives

The ShibbolethDisable directive can be used to disable support for a specific version of Shibboleth. Sample use:

ShibbolethDisable 1.3 ShibbolethDisable 2.1

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.

Syntax:

ShibbolethMetadata \ -EntityID= EZproxyEntityID \ -File= MetadataFile \ [-Cert= EZproxyCertNumber \] [-URL= MetadataURL \] [-URLValidate= URLValidateFile \] [-AuthnContextClassRef= AuthnContext]

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 (\).

-EntityID= EZproxyEntityID: This required parameter specifies the Entity ID for the EZproxy server when using this metadata.
-File= MetadataFile: 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.
-Cert= EZproxyCertNumber: 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.
-URL= MetadataURL: 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.
-URLValidate= URLValidateFile: 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.
-AuthnContextClassRef= AuthnContext: 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.

Routing users to Shibboleth for authentication

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:

DSURL: A URL for a Shibboleth 2.1 Discovery Service.
EZproxyEntityID: An Entity ID used to identify your EZproxy server.
IDPEntityID: An Entity ID used to identify an Identity Provider.
WAYFURL: 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:

::Shibboleth IDP13 IDPEntityID /Shibboleth

To route users to a Shibboleth 1.3 WAYF, use a configuration similar to this in user.txt:

::Shibboleth WAYF13 WAYFURL WAYF13 -EntityID= EZproxyEntityiD WAYFURL /Shibboleth

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:

::Shibboleth IDP20 IDPEntityID /Shibboleth

To route users to a Shibboleth 2.1 Discovery Service, use a configuration similar to this in user.txt:

::Shibboleth DS20 DSURL DS20 -EntityID= EZproxyEntityID DSURL /Shibboleth

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:

::Shibboleth If login:auth eq "shibboleth"; IDP20 IDPEntityID /Shibboleth

adding

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.

shibuser.txt

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"); Deny unaffiliated.html If auth:urn:mace:dir:attribute-def:eduPersonPrimaryAffiliation eq "alum"; Deny alum.html Group Default If Any(auth:urn:mace:dir:attribute-def:eduPersonAffiliation, "employee"); Group +Employee If Count(auth:urn:mace:dir:attribute-def:eduPersonScopedAffiliation@law.example.edu) > 0; Group +Law If auth:urn:mace:dir:attribute-def:eduPersonPrincipalName@example.edu eq "ezmgr"; Admin 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.

See Common Conditions and Action for additional directives that can be used in shibuser.txt and Expressions for additional comparison, string, and numeric operations.

Quick configuration

Access the EZproxy administration page.
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 the EZproxy administration page, access SSL Configuration. If you do not have an appropriate certificate for communicating with your Identity Provider, create or import one here. 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:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

to something like this:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID=" your-entity-id-here">
From the EZproxy administration page, access Manage Shibboleth. You will need to provide the Shibboleth 1.3 Assertion Consumer Service URL and/or Shibboleth 2.1 Assertion Consumer Service URL to the person who manages your metadata.
Provide the certificate data and Assertion Consumer Service URL(s) to the person who manages your metadata. This person will need to update the metadata and provide you either either a copy of the metadata or a URL where you can access the updated metadata.
If you are provided with a metadata file, place it in the directory where EZproxy is installed. If you will download the metadata and have been provided with a certificate to validate the data you download by URL, place that file in the directory where EZproxy is installed.
Edit config.txt and change your ShibbolethMetadata directives to reflect your actual EZproxyEntityID, MetadataFile, and EZproxyCertNumber, such as:

ShibbolethMetadata \    -EntityID= EZproxyEntityID \    -File= MetadataFile \    -Cert= EZproxyCertNumber

If you have a URL to download the metadata, include this as well, such as:

ShibbolethMetadata \    -EntityID= EZproxyEntityID \    -File= MetadataFile \    -Cert= EZproxyCertNumber \    -URL= MetadataURL

If you also have a file with a certificate to validate the data retrieved from the URL, incorporate that, such as:

ShibbolethMetadata \    -EntityID= EZproxyEntityID \    -File= MetadataFile \    -Cert= EZproxyCertNumber \    -URL= MetadataURL \    -URLValidate= URLValidateFile
From the EZproxy administration page, use the option to restart EZproxy.
From the EZproxy administration page, use the option to view the last 100 lines of messages.txt to verify if there were any errors detected with the ShibbolethMetadata directive.
From the EZproxy administration page, use Manage Shibboleth. Try to access an Identity Provider to have attributes released. If attributes are released, EZproxy will provide a suggested basic entry for use in the user.txt file to route EZproxy users to your Identity Provider for authentication.

User authentication