EZproxy SAML Authentication at Scale

KYVL has leveraged EZproxy's capacity to configure multiple authentication servers to scale SAML authentication for Kentucky's K12 school districts and other KYVL member institutions.

We've documented our processes for both EZproxy admins and institutional IT staff. The resources assembled here should enable any EZproxy instance to achieve similar results for your users.

KYVL's EZproxy is self-hosted. We are on version 7.1.11 GA.

We are grateful to the IT teams at Owensboro Public Schools and Jefferson County Public Schools, early implementation partners who made it possible for us to navigate in unfamiliar waters. This project could not have succeeded without their expertise and patient collaboration.

Additional thanks to previously unknown EZproxy listserv colleagues, OCLC's EZproxy support, and the Kentucky Department of Education's Office of Education Technology.

This 18-second clip illustrates successful email login using SAML authentication in EZproxy.

The clip begins when the user is directed to KYVL's EZproxy login.htm page after clicking a proxied link for Britannica School.

In this example, the user logs in with a Google email address and is redirected to Azure AD as identity provider.

When multiple authentication servers are configured in user.txt, EZproxy's default behavior is to try each authentication server in sequence.

This can result in "an unacceptable delay in authenticati[ng] users who validate against entries later in user.txt."

EZproxy's Multiple authentication servers documentation includes examples of login page code to direct users to the correct authentication server based on user selection, e.g., student or faculty.

KYVL uses javascript on the login page to assign an auth value based on the user's email address. That auth value enables EZproxy to direct the user to the correct authentication server without user intervention.

Follow the steps to the right
as Peter Parker logs in.

For a closer look at the underlying html and javascript, visit proxy.kyvl.org/login and loginFormAllSaml.js.

Documentation is available from OCLC to assist in configuring EZproxy for SAML authentication. For those unfamiliar with the terminology, however, the instructions can be confusing. 

For current purposes, 

• Identity provider (IdP) refers to Google or Azure AD.
• EZproxy is the service provider (SP).
• Each service provider and identity provider is identified by a unique entityID, which is part of each party's metadata.
• Each party's metadata also includes one or more X509 certificates (certs). These certificates expire.
• Service providers and identity providers exchange metadata.
• Metadata is formatted as xml. IdP's send their metadata to EZproxy administrators, who upload it to the server.
• Only two small bits of EZproxy metadata, not the entire xml file, are needed by each IdP. 

EZproxy metadata can be found in EZproxy Adminstration > Manage SSL (https) Certificates.

To find the values you will need, click the number of the certificate you will use for your SAML connections.

On the next screen, select one of the View Shibboleth metadata for this certificate options.

EZproxy requires an active SSL certificate for SAML connections.

If needed, visit EZproxy Administration > Manage SSL (https) certificates, and select Create New or Import Existing SSL Certificate.

For more information, see How do I generate metadata for SAML connection to EZproxy or OCLC EZproxy support documentation at the end of this guide.

Make note of two metadata values - your entityID and AssertionConsumerService (POST) Location.

For KYVL these values are:

entityID (KYVL)

https://proxy.kyvl.org

Location (KYVL):

https://login.proxy.kyvl.org/
Shibboleth.sso/SAML2/POST

These values are needed by IdPs for use in configuring Azure AD or Google for SAML Login.

Google and Azure AD configuration steps are outlined in these KYVL tutorials. Be sure to substitute your EZproxy metadata values for the KYVL values shown.

As local admins share their metadata in the process of app configuration, EZproxy admins should note entityIDs as metadata is received. EntityIDs are used in EZproxy's user.txt file during SAML configuration.

KYVL maintains a spreadsheet of key data points for each SAML instance we configure. A template is included among the KYVL sample documents in the resources section at the end of this guide.

One more note regarding metadata. Certs expire - your own EZproxy metadata and the metadata provided by your IdPs.

• Be sure to note the validUntil date included in each Google metadata file. Instructions for renewing a Google SAML certificate can be found in this tutorial.
• Azure AD metadata is valid for three years from creation of the app. Microsoft provides this tutorial for managing certificates.

Future-proof your SAML connection by loading new metadata into EZproxy before certificate expiration.

Once IdP metadata is received and logged, it's time to add a SAML connection in EZproxy. The process is simple and can be completed in about five minutes.

There is no limit to the number of authentication servers you can add. KYVL currently has over 80 configured!

KYVL uses Notepad++ to edit all the files used in configuring each SAML instance. Download here or in the resource section.

KYVL renames each metadata file auth.xml to match the auth value assigned by the javascript on the login page, generally the district name from a user's email.

KYVL created a folder called includeShib the main EZproxy directory as the destination folder for metadata .xml files.

The combined path and file name for each metadata file, e.g., /includeShib/mydistrict.xml, appears in a ShibbolethMetadata directive in config.txt.

KYVL's user.txt Shibboleth configuration follows the pattern shown in the OCLC documentation, but includes scores of statements in the form

If login:auth eq

Some things to note:

• Shibboleth configuration begins with ::Shibboleth and ends with /Shibboleth.
• Do not leave uncommented spaces between lines or errors will result.
• Login:auth eq "authname" is assigned by login page javascript and corresponds to an xml file name in config.txt. 
• Commented (#) lines are placeholders.
• EZproxy restart after edits to user.txt is not required.

"The position-independent ShibbolethMetadata directive ... link[s] EZproxy to your Identity Providers ... [It] may appear multiple times."

The first time you create this directive, carefully follow the prescribed format. KYVL uses required values only.

ShibbolethMetadata \
   -EntityID=EZproxyEntityID \
   -File=MetadataFile \
   -SignResponse=false -SignAssertion=true -EncryptAssertion=false \

• EZproxyEntityID must match the EZproxy metadata. KYVL's value is https://proxy.kyvl.org.
• MetadataFile includes path and file name, e.g., includeShib/filename.xml.
• KYVL uses the values shown for SignResponse, SignAssertion and EncryptAssertion.

For each IdPs added, copy and paste the whole directive, editing only the filename for the new IdP.

For more information, see SAML Authentication #config.txt directives.

EZproxy restart is required for edits to config.txt to take effect. This can be postponed briefly pending edits to login.js.

One last edit.

The newly configured district needs to be added to the list of configured districts in login.js (or in KYVL's case, loginFormAllSaml.js).

Public school districts and other IdPs are handled differently by the javascript, so KYVL's javascript maintains separate alphabetized lists.

Use caution when editing! The code is unforgiving. A misplaced comma or quotation mark can break the whole thing.

Save changes and RESTART EZproxy!

If the district / local admin has provided test credentials, KYVL does initial testing. If not, we ask the district to test and confirm the results.

Begin with proxied database link such as Britannica School and enter the test credentials.

Note: It's important to test using a clean browser.

• An incognito window typically works well.
• Residual logins result in a 403 Error: app_not_configured_for_user.
• <Ctrl><Shift><Delete> in Chrome opens a dialog box that enables user to clears all data.

Did you authenticate successfully? Woohoo! It's time to share the good news with the IdP.

If not, it's time to begin troubleshooting.

Lots of configurations work right away but initial failure is frequent. Many errors can be resolved easily, while others are confounding.

Revisiting each configuration step is a good double-check, as is, at times, asking the IdP to go through the configuration tutorial steps again and send new metadata.

Common errors and solutions

• 403 - App not configured for user
  • Logged in with another IDP. Clear cache and retry.
  • Cut and paste error. Check those changes in user.txt and config.txt!
• 400 - Malformed cert
  • Cert may be expired. Complete cert renewal tutorial.
• 403 - Not a SAML app
  • This sometimes resolves on its own with a little time.

KYVL is continuing to build out its troubleshooting reference. Check back and please share any problems you've encountered and steps you've taken to solve them.

Some web pages to try

• SAML app error messages
• All my patrons are signing in with the username Shibboleth in EZproxy, what should I do to possibly fix this?
• Why am I getting Inter-institutional access failure. Please contact your system administrator for assistance. when using SAML authentication and EZproxy