SAML Authentication (including Shibboleth V1/2/3, ADFS, Microsoft Entra ID (Azure), OpenAthens)

Overview

Configuring EZproxy for SAML 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.

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.

Term	Definition
Discovery Service (DS)	A Shibboleth 2.x3/x 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 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 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 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: Sign and encrypt data for use with Shibboleth 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 SAML. Sample use:

ShibbolethDisable 1.3
ShibbolethDisable 1.2

The position-independent ShibbolethMetadata directive is used in config.txt to link EZproxy to your Identity Providers. This directive may appear multiple times to link EZproxy to multiple federations.

Syntax for 6.6.2 and newer:

ShibbolethMetadata \
   -EntityID=EZproxyEntityID \
   -File=MetadataFile \
   -SignResponse=false -SignAssertion=true -EncryptAssertion=false \
   [-Cert=EZproxyCertNumber \]
   [-SignAuthnRequest \]
   [-SLO \]
   [-URL=MetadataURL \]
   [-URLValidate=URLValidateFile \]
   [-AuthnContextClassRef=AuthnContext]

Note: The values for -SignResponse=false -SignAssertion=true -EncryptAssertion=false \ are dependent on configuration of your SAML server.

Syntax for 6.5.x and below:

ShibbolethMetadata \
   -EntityID=EZproxyEntityID \
   -File=MetadataFile \
   [-Cert=EZproxyCertNumber \]
   [-SignAuthnRequest \]
   [-SLO \]
   [-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 be 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 (\).

Value	Definition
`EZproxyEntityID`	This required parameter specifies the Entity ID for the EZproxy server when using this metadata.
`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.
`EZproxyCertNumber` (Optional)	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. EZproxy defaults to the active SSL certificate if this value is not defined.
`-SignAuthnRequest` (Optional)	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.
`-SLO` (Optional)	See Beta Support for Shibboleth Single Logout
`MetadataURL` (Optional)	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.
`URLValidateFile` (Optional)	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. Currently, the metadata validation needs the metadata to contain an EntitiesDescriptor element, which then contains one or more EntityDescriptor elements.
`AuthnContext` (Optional)	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.
`SignResponse` (Optional)	This optional parameter is used when processing a Response document from an IdP. This value determines whether or not the Response document must be signed. The default value is true.
`SignAssertion` (Optional)	This optional parameter is used when processing a Response document from an IdP. This value determines whether or not the Assertion within the Response must be signed. The default value is false. Caution: Earlier versions of EZproxy would accept Response documents in which the Response was not signed, the Assertion was signed, and the Assertion was not encrypted. With the release of EZproxy v6.6.2, any site relying on this behavior will need to add the following to their ShibbolethMetadata directive: -SignResponse=false -SignAssertion=true -EncryptAssertion=false
`EncryptAssertion` (Optional)	This optional parameter is used when processing a Response document from an IdP. This value determines whether or not the Assertion within the Response document must be encrypted. The default value is true.

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.

Debugging

Option LogSAML specifies that EZproxy should store copies of Security Assertion Markup Language (SAML) documents during SAML authentication for debugging. For more information, see Option LogSAML.

Routing Users to SAML 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:

Abbreviation	Description
`DSURL`	A URL for a Shibboleth 2.x/3.x 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.

Shibboleth 1.3 Configurations

To route users to a specific SAML 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.

Shibboleth 2.x/3.x Configurations

To route users to a specific SAML 2.x/3.x Identity Provider, use a configuration similar to this in user.txt:

::Shibboleth
IDP20 IDPEntityID
/Shibboleth

To route users to a Shibboleth 2.x/3.x 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.

Mixing Traditional EZproxy Authentication with SAML

If you want to mix traditional EZproxy authentication options with SAML, 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 SAML routing method you use.

Users who want to login with SAML will click this special link, whereas other users will use the login form.

shibuser.txt

This file allows the use of SAML 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.

Note: If special characters (i.e., colons) are used, include quotation marks.
Example: auth:"urn:oid:1.3.6.1.4.1.5923.1.1.1.7"

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 Any(auth:"http://schemas.xmlsoap.org/claims/Group", "Staff"); Stop

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 SAML 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 SAML 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-ezproxy-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.x/3.x Assertion Consumer Service URL to the person who manages your metadata. These values are also included in the metadata file generated from EZproxy.
Provide the certificate data and Assertion Consumer Service URL(s) or EZproxy metadata file to the person who manages your SAML system. This person will need to provide you a copy of the Identity Provider metadata or a URL where you can access the 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 \ 
    -SignResponse=false -SignAssertion=true -EncryptAssertion=false \
    -Cert=EZproxyCertNumber

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

ShibbolethMetadata \ 
    -EntityID=EZproxyEntityID \ 
    -File=MetadataFile \ 
    -SignResponse=false -SignAssertion=true -EncryptAssertion=false \
    -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 \ 
    -SignResponse=false -SignAssertion=true -EncryptAssertion=false \
    -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.

ADFS and EZproxy

ADFS can be used with SAML 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 SAML authentication, follow the instructions below to create and configure a relying party trust within ADFS for EZproxy.

ADFS Metadata

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:

https://ADFS instance name/FederationMetadata/2007-06/FederationMetadata.xml

Note: Replace "ADFS instance name" with your institution's instance name.

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.

For sites that do not want to log specific usernames in their logs, use the following configuration to avoid the encrypted string logging:

ifIssuer = "url"; setlogin:loguser

Create a Relying Party Trust

Follow these steps to create a relying party trust for use with EZproxy on your ADFS server.

Launch the ADFS 2.0 Management Console on your ADFS server.
Under Trust Relationship, click Relying Party Trusts > Add Relying Party Trust.
A wizard will appear, which will guide you through the process of creating the Relying Party Trust. Click Start.
In the Select Data Source window, select the type of metadata you will be entering. This information comes from your service provider. You can use a URL, import an XML file, or configure it manually. Select import data about the relying party from a file and browse to the appropriate metadata file. Click Next.
A window will open stating some of the content in the federation metadata was skipped because it's not supported by ADFS 2.0. These are just items that pertain to ADFS 1.0. Click OK.
Specify a Display Name for the trust and enter any notes you may have. Click Next.
Select Permit all users to access this relying party and click Next.
A summary window will show each item that will be configured for the trust that was provided by the metadata. Here you can review the identifiers, endpoints, encryption certificate, etc. After reviewing, click Next.
A new window will appear stating the relying party trust was successfully added. A check box will be selected to Open the Edit Claim Rules dialog. Leave this checked and click Close.
Once the wizard has closed a new window will appear where you can add the claim rules to the trust. Click Add Rule to begin the process.
The add transform claim rule wizard will launch. Here you will select your claim rule template. Select Send LDAP Attributes as Claims from the drop-down menu and click Next.
In the next window, configure your claim rules. Enter a Claim rule name. Select Active Directory from the Attribute store drop-down. For example, to send a user's email address as an outgoing claim as Name ID: under LDAP Attribute, select Email Address; under Outgoing Claim Type, select Name ID. Click Finish.
The wizard will close, and you now have successfully created a claim rule to be used with the trust. Click OK to complete the process.
Now that the trust and claim rule are in place, right-click on the trust that was just created and click Properties. A window will open that will display the elements configured for the trust. The certificate that contained the metadata provided by the service provider will be found on the Signature tab. This certificate will need to be exported and installed to the Personal certificate store of the ADFS host. Double click the entry to bring up the certificate. If the certificate isn't trusted, it will also need to be installed to the Trusted Root certificate store. Without having the certificate in the Personal certificate store, ADFS will not be able to sign the assertion.
Once the certificate has been installed, the hash algorithm will need to be confirmed. By default, ADFS sets the secure hash on the trust to SHA-256. Visit the details of the certificate to determine the hash algorithm.
The trust is now complete for EZproxy. Use the URL provided to test authentication.

Beta Support for Shibboleth Single Logout

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:

ShibbolethMetadata \
    -EntityID=EZproxyEntityID \
    -SLO \
    -File=MetadataFile \
    -URL=MetadataURL \

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:

If the user accesses the EZproxy /logout URL such as https://login.ezproxy.yourlib.org/logout and if the user originally authenticated via Shibboleth, EZproxy will send a Single Logout request to the Identity Provider and expects to receive a Single Logout response.
If the user accesses the logout option of their Identity Provider, the Identity Provider can send a Single Logout request to EZproxy and EZproxy will send back a Single Logout Response.
In either scenario, the Identity Provider is responsible for coordinating the logout requests to any other servers that have authenticated in the same session.

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.