Administering OpenAthens Authentication:

An Introductory Toolkit for Librarians

OpenAthens offers ISO 27001 standard-compliant, federated Security Assertion Markup Language (SAML) based authentication for patrons remotely accessing library subscribed e-resources from off-site locations. At The University of Toledo Libraries, we utilize optional integrations with university IT maintained software systems so that patron authentication is confirmed via successful login with the university’s single sign-on, which grants OpenAthens-level authorizations for the patron’s active web browser session. With anonymization methods in place, OpenAthens then interacts with e-resource sites in the background to unlock library-subscribed content based on the patron’s locally set e-resource allocations, without the patron’s active participation in each resource-specific login workflow. Among other benefits, OpenAthens limits the number of unique username/password combinations a patron must maintain for remote library access, reducing patron clicks when accessing multiple subscribed resources during a single browser session. Our use of the optional integrations allows patron roster maintenance and its primary security to remain under university IT control, while allowing library staff to allocate and maintain connections between OpenAthens and hundreds of e-resources as subscription statuses change.

Utilizing EBSCO’s setup service, The University of Toledo Libraries went live with OpenAthens authentication in August 2019. The EBSCO team provided expert support during the transition process, including “athenized” URLs for existing databases and collection-level resources for our local users. From there, library staff quickly began updating the patron-facing A to Z database list and LibGuide link assets, proxy prefixes and IP addresses in resource administrator accounts, and much more before the beginning of the Fall 2019 semester. But what happened after the OpenAthens implementation team and the library staff considered the setup project complete? How did library staff determine e-book or e-journal title-level URLs? It was time for library staff to dig in deeper and start working our way through some OpenAthens tasks on our own. Support tickets can still be placed as needed with OpenAthens, and formal training sessions can be arranged, but below is a brief overview of some freely available resources that helped during our fledging period and beyond. Whether you are completely new to OpenAthens from the library perspective or are seeking informal help with cross-training colleagues, this collection of resources represents the basic tools regularly utilized by one librarian responsible for locally managing this library authentication software.

Tools for Adding New Resource Connections

One of the first OpenAthens tasks The University of Toledo Libraries were responsible for after the implementation was the addition of a new resource connection. When completing this task for the first time, the OpenAthens documentation website was critically important, even if a little confusing on the first couple of read-throughs. The new users page will likely be your most used reference as you work your way through the first months after OpenAthens go-live.

Whether your library stores important resource information in shared Excel sheets or in ERM system records, there is a set of local OpenAthens information, unique to your organization, that may be requested by resource providers when setting up a new resource for OpenAthens authentication. This local information should be made readily available to all library staff who will be responsible for setting up authentication for newly acquired or subscribed e-resources. The information includes your organization’s:

• OpenAthens Domain
• OpenAthens IP Address (for proxy connections)
• OpenAthens Organization ID
• OpenAthens Entity ID
• OpenAthens Redirector Prefix

Tools for Athenized URL Building

Redirector Compatible

Similar to EZProxy and WAM Proxy solutions that provide prefixes and other affixes for generating URLs that direct library patrons through a library’s authentication process for remote access, OpenAthens libraries will be given their unique OpenAthens redirector prefix.

Basic redirector prefix structure:
https://go.openathens.net/redirector/YOUROPENATHENSDOMAIN?url=

This prefix works for connecting to a large swath of locally acquired resources through the OpenAthens authentication pathway, whether the actual resource connection is a proxy setup or a federated/SAML connection. To confirm that a resource is redirector compatible, visit the list of redirector compatible providers maintained by OpenAthens. This web resource was recently redesigned to move away from a long-scrolling, text-based alphabetical listing that used symbols to distinguish redirector compatible resources and other specific resource characteristics. The OpenAthens team has added better search capability and resource filters so that librarians can more easily discern what “flavor” of connection is currently offered for resources from a particular provider or publisher. For those librarians unfamiliar with working in a federation mindset, you will want to confirm, likely with your IT department, which of the federations your organization is a member of, as a small assortment is also indicated on the compatible providers list. If a specific provider/resource is not currently available for your organization’s existing member federation(s) or does not support SAML in general, you will likely request setting up authentication as a traditional proxy connection via an OpenAthens Support ticket, at least in the short term. This is assumed because, whether it is your organization or a resource provider joining an additional federation, it can take deliberation and more involved technology adjustments by IT administrators before federation membership becomes operational.

Target URL Encoding

For some resources, simply adding the redirector prefix onto the front of the resource’s base access URL (the target URL) will be adequate. However, on their redirector link generator documentation page, OpenAthens does recommend percent encoding, sometimes known as URL encoding, for most target URLs. The use of special characters like % and = within target URLs can confuse the system, ending in misdirection or error pages from the patron’s perspective. At The University of Toledo, we found these special characters particularly common when determining athenized URLs for e-books at the individual title or chapter level. To add the redirector prefix and complete the encoding, you may input the target URL into the redirector link generator specific to your organization within your library’s OpenAthens admin account under the Resources tab, or use the publicly available link generator provided by OpenAthens and customizable to your organization. Though I recommend storing the local redirector prefix within the ERM record or spreadsheet with the other items listed in the section above, a wider group of technical services and public services staff will likely need ready access to the local prefix. You may wish to add a bookmark to your institution’s publicly available OpenAthens redirector link generator within a LibGuide or other convenient location for wider distribution to library staff and patrons. For those circumstances when you might need to determine some percent encoding on your own or want to learn a little more about this format, free webpages exist for this purpose, such as the URL Decode and Encode tool.

As a charter institution of the OhioLINK consortium, we regularly enjoy collaborative troubleshooting and learning with our talented colleagues at other OhioLINK libraries when technology issues arise. However, The University of Toledo was only the second OhioLINK institution to implement OpenAthens authentication. Through web searches and other discovery methods, we explored the ways existing OpenAthens institutions in the global community had solved some of the subcollection linking problems we had been experiencing. For example, when we gained access to Films On Demand in early 2021, we needed to record the redirector prefix within the Films On Demand administration site for generating platform permalinks that would be presented to patrons for individual videos. Unfortunately, for the output permalinks to work, the Films On Demand target URL also needed to be encoded. This temporarily presented a local problem as staff lacked technical knowledge for forcing the permalink generator to encode everything after the redirector prefix. Likewise, directing patrons to take the additional step of copy and pasting a Films On Demand generated permalink into the redirector link generator to retrieve a usable URL was deemed too cumbersome for the patron workflow. Knowing the general sizes of the customer bases for both Films On Demand and OpenAthens, we reasoned that we could not be the first library to approach this issue. Conducting a web search with basic search phrases like +“Films On Demand” +“OpenAthens”, we found the solution to our problems by seeing the links other libraries were providing to Films On Demand videos. The University of Toledo Libraries express gratitude to the Florida Academic Library Services Cooperative for their public LibGuide on OpenAthens, particularly their page “Permalinks That Require HEX Code Encoding,” which introduced local staff to EBSCO’s Proxify Tool prefix:

https://widgets.ebscohost.com/prod/customlink/proxify/proxify.php?count=1&encode=1&proxy=https://go.openathens.net/redirector/YOUROPENATHENSDOMAIN?url=

EBSCO’s Proxify Tool prefix allows one to both use the organization’s redirector prefix and force URL encoding on whatever target URL is appended to the end. This new-to-us prefix offers great potential for our collection services department to explore further, as we have experienced challenges in the past with determining a quick method for rapidly updating URLs in existing MARC records with the necessary URL encoding. Alternatively, in the redirector link generator portion of the Resources tab within the OpenAthens administration site, a method for batch encoding target URLs by uploading a formatted .csv or .txt file has also been recently added.

Searching for athenized links from other OpenAthens libraries’ A to Z lists or websites is a great starting point when attempting to troubleshoot a new resource URL to provide to your own patrons. The examples you uncover may not match up exactly to what your specific library may need, but typically provides the necessary hints for finding a way around obstacles.

WAYFLess (Where Are You From) URLs

Though seemingly less frequent now, at the time of our OpenAthens implementation some resources appeared to prefer use of the resource provider’s unique WAYFLess URL structure rather than readily allowing use of the redirector prefix. For an example of a WAYFLess URL structure, on their authentication support page, Credo Reference offers subscribers the following WAYFLess URL structure:

https://connect.openathens.net/credoreference.com/456a79ee-132b-4228-8d50-39918f628abe/login?entity=https%3A%2F%2Fidp.***.edu%2Fopenathens&target=https%3A%2F%2Fsearch.credoreference.com

In the example above, the *** would be replaced with the subscribing library/institution’s unique information so that the patron is still automatically routed past the “where are you from” institution selection page on the e-resource website. Anecdotally, WAYFLess URLs seem to provide quicker page load times, but this makes the URL structure less predictable to library patrons. Since each has its benefits, your local staff may want to discuss some general local guidelines as to when it may be preferable to promote one style over the other. Typically, resource platforms that provide permalink generators for patron use resolve much of the human error that would have otherwise occurred with WAYFLess URLs, allowing patrons to successfully copy and paste appropriate URLs for reconnecting to specific items on and off campus. Information regarding a specific resource or resource provider’s WAYFLess URL structure is typically found by conducting a keyword search for WAYFLess on the resource provider’s support documentation website.

Tools for Troubleshooting, Connecting, and Learning More Moving Forward

Admittedly, during the height of the global COVID-19 pandemic, greater focus was required for providing patron support, budgeting, and technology troubleshooting. This had placed some projects for greater OpenAthens integration planned for 2020 and 2021 at a much lower priority than we initially intended. When our Interlibrary Loan team sought to revive a coordinated project to work towards integration of our ILLiad instance with OpenAthens authentication, I was pleasantly surprised by some of the advances and developments we had missed in the wider OpenAthens community. This was especially true of the OpenAthens customer listserv, which kicked off in May 2020. Providing a valuable space for OpenAthens libraries to converse with each other as well as with OpenAthens moderators, this fills a need that we felt was absent during The University of Toledo’s OpenAthens implementation. The listserv provides a timely outlet for asking OpenAthens related questions that might not merit a support ticket, a sounding board for further innovation, and opportunity for quickly polling the community as to whether a resource authentication error is locally contained or affecting a broader customer base. Those wishing to subscribe may do so from the OPENATHENS listerv homepage. Additionally, the listserv archive can be searched for problems others might have previously addressed, including information on the availability of ILLiad/OpenAthens authentication integration.

The OpenAthens team also launched a known resource issue support page, which is a good first stop before taking questions to the listserv. Dissimilar to status pages, such as EBSCO’s Status page, the original intention of the OpenAthens Access Issues webpage did not appear to be for providing notice of very temporary resource outages or disconnections. It did, however, provide a helpful global view for library staff administering OpenAthens as more e-resources implement upgrades and continue to move from proxy connections to federated ones. This resource information relocated to the OpenAthens Resource Status Page, newly launched in June 2022, with the addition of a timestamped history of reported resource incidents one might have expected from the original OpenAthens Access Issues webpage. This resource, as well as the customer listserv and more tailored emails from OpenAthens based on locally allocated resource connections, have begun to address communication shortfalls experienced early on in our OpenAthens implementation. Previously, as resources switched from a proxy connection to a federated/SAML connection, the existing proxy connection pathway would fail on and after the federated connection’s go-live date. Libraries were not always kept informed of these transitions by the resource providers or OpenAthens. This led to surprise forbidden error messaging to library patrons, which usually required a few minutes of hurried work on the library administrator’s part to allocate the most current connection for the resource within the Resources tab on the OpenAthens Administration site.

Library staff who need to monitor communications from OpenAthens of scheduled maintenance windows and any unexpected service outages that may occur should “Subscribe to Updates” on the actual OpenAthens Status Page to receive email notifications.

As more libraries and consortia adopt OpenAthens authentication, I predict we will see additional LibGuides made publicly available covering common and uncommon situations in the OpenAthens implementation and maintenance workflows. These would provide further reference sources for supporting librarians working through a local implementation with a smaller staff or a particularly challenging innovation or issue. But for now, we are frequently seeing a response to our information needs both from within the library community and by OpenAthens staff, regularly expanding our toolkit.