Skip to Main Content

EZproxy SAML Authentication at Scale

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.


Multiple Authentication Servers

Multiple authentication servers in user.txt

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 and loginFormAllSaml.js.

Student Peter Parker ( clicks on a proxied Britannica link.

He enters his school email address when prompted to log in. The login page uses javascript to parse his email address.

user =
username = peter.parker
domain =
district = mydistrict

If mydistrict is found in the loginForm.js among the districts configured for SAML, the javascript rewrites the requested URL, adding an auth parameter with value set to the district name.

This new link directs EZproxy to search user.txt for instructions on how to authenticate a user with an auth value of mydistrict

If login:auth eq "mydistrict"; IDP20

user.txt entry with the corresponding auth value sends the user directly to the correct authentication server, where he will complete the login process using his mydistrict credentials.

Terms and documentation

Simplified terms

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. 

View EZproxy Metadata

View EZproxy metadata

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.

A note about certificates

EZproxy requires an active SSL certificate for SAML connections.

If needed, visit EZproxy AdministrationManage 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.



Key EZproxy metadata values

Note entityID and Location values

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

For KYVL these values are:

entityID (KYVL)

Location (KYVL):

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.

IdP Metadata

IdP Metadata

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.


Configuration Steps

Configuration steps

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.

  1. Upload metadata.xml file
  2. Edit user.txt
  3. Edit config.txt
  4. Edit loginPage.js
  5. RESTART EZproxy

Upload Metadata

Upload xml

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.


Add ShibbolethMetadata directives to config.txt

"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
  • 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.

Edit Javascript

Update the javascript

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!



Time to test!

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.


Errors and resources

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
  • 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.


KYVL Tutorials

Substitute your EZproxy metadata values for the KYVL values shown in the tutorials.
Refer to Key EZproxy Metadata Values in this guide.

KYVL Sample Docs - HTML, JS, Tracking

OCLC EZproxy Support Documentation

Google Workspace Admin Help

Microsoft Ignite

Other Resources

KVYL uses Notepad++ to edit all the files needed for each SAML configuration - metadata.xml, login.htm, login.js, config.txt and user.txt.