Understanding EZProxy

What is EZProxy?

EZProxy is a very popular reference middleware solution developed by OCLC (Online Computer Library Center), used by universities worldwide to provide secure and controlled access to electronic resources and subscriptions. It combines IP proxy, SSO Proxy, Where Are You From (WAYF) service (aka, IdP Discovery Service) and access mode switch capabilities to accomplish this managed access based on user location (on/off-campus) and authentication status.

This diagram shows how access to resources is managed by EZProxy on a high level:

flowchart LR
    classDef decision fill:#f9f,stroke:#333,color:#000
    classDef action fill:#bbf,stroke:#333,color:#000
    classDef endpoint fill:#dfd,stroke:#333,color:#000

    U[User Request]:::action --> L{Location<br/>Check}:::decision
    L -->|On-Campus| D[Direct Access<br/>to Resource]:::endpoint
    L -->|Off-Campus| A{Authentication<br/>Required}:::decision
    A -->|Not Authenticated| E[Request<br/>Authentication]:::action
    E --> A
    A -->|Authenticated| P{Resource<br/>Permissions}:::decision
    P -->|Allowed| R[Route Through<br/>Proxy Server]:::action
    P -->|Denied| X[Access<br/>Denied]:::endpoint
    R --> D

Key Concepts

EZProxy Does Not Provide Authentication

EZProxy does not provide an authentication solution bundled, but instead uses customized authentication settings in the users.txt configuration file (or ezproxy.usr for hosted instances). OCLC provides a list of supported authentication methods.

Instead, EZProxy relies on an existing IdP and serves as an SSO proxy that manages sessions.

Deployment Models

EZProxy is available in two flavors:

Fully managed by OCLC: Hosted solution where OCLC handles infrastructure
Self-hosted: Institution manages their own infrastructure

In both cases, an administration team is responsible for configuration and maintenance.

Configuration Architecture

Configuration consists of defining a list of accessible resources/databases in a config.txt file (or ezproxy.cfg for hosted instances), with each entry being a set of up to six directives called stanzas.

Technical Architecture

EZProxy relies on various protocols and technologies to facilitate its main goal of organizing and managing access to resources database of electronic assets and content providers. At its core, it plays the middleman role and deals with all content provider authentication requirements, handling authentication and authorization by acting as an IP proxy.

Authorization Model

The core concept of authorization for EZProxy revolves around the exchange of Assertions (security tokens), mainly based on the Shibboleth protocol (for all considerations in this section, Shibboleth is considered an implementation of SAML). In a nutshell, EZProxy exchanges assertions with the configured IdP using SAML or SAML compliant authentication and reflects those configurations and mappings in the shibuser.txt configuration file to establish a group-based access control.

IP Proxy Functionality

The main selling point for EZProxy is to gather and control all resource access requests, and pose them as coming from a single public IP associated with the corresponding instance of the EZProxy service for the institution. This functionality relies on the content provider (Statista) being able to identify requests from this IP and handle them as trusted (coming from a registered IP associated to an active account).

Where Are You From (WAYF) / URL Rewriting

EZProxy provides a URL rewriting feature to deliver content from providers to end users. Since content is requested on behalf of the patrons of a certain institution, and they are required to be authenticated (on-campus) and authorized (on-campus and off-campus), combined with the potential of multiple authentication methods, in order to relieve users from going multiple times through the WAYF process, the content URL is rewritten to include this information and looks something like www-statista-com.statista.idm.oclc.org.

This approach comes with several downsides:

Additional EZProxy cookie policies configuration required
Domain conflicts when dealing with calls originating from the IP proxy
Confusion for end users - to access the Statista website, they have to navigate to a catalog of services and use the WAYF-less URL provided
Makes it hard to provide full-url redirects (or distribute links for the original source's domain, e.g. statista.com), forcing content providers to rely solely on relative links so that their URLs are not broken by directing users around the proxy

How EZProxy Works with Statista

Access Flow

sequenceDiagram
    actor U as User
    participant B as Browser
    participant D as Database Provider
    participant E as EZProxy Server
    participant I as Institution IdP
    participant S as Content Provider<br>(statista.com)

    Note over U,S: On-Campus Access
    activate U
    U->>+B: Search for institution content resource
    B->>+D: Query for managed resources
    D-->>-B: Search results
    B-->>-U: Presents search results list
    U->>+B: Selects desired resource (Statista)
    B->>+E: Proxied request
    E->>E: Is an EZProxy managed resource
    E->>E: User is on campus
    E->>E: Has EZProxy session
    E->>E: Group/User is authorized
    E->>+S: Request access to paid content
    S->>S: Check IP address of requester<br>against registered CIDRs
    S-->>-E: Address found!<br>Send content
    E->>E: Generate WAYF-less URL
    E-->>-B: Content under WAYF-less URL
    B-->>-U: Result details
    deactivate U

    Note over U,S: Remote Access via EZProxy
    activate U
    U->>+B: Search for institution content resource
    B->>+D: Query for managed resources
    D-->>-B: Search results
    B-->>-U: Presents search results list
    U->>+B: Selects desired resource (Statista)
    B->>+E: Proxied request
    E->>E: Is an EZProxy managed resource
    E->>E: User is off-campus
    E-->>-B: Redirect: to IdP
    B->>+I: Authentication request
    I-->>-B: Prompt for credentials
    B-->>-U: Login page
    U->>+B: Username and password
    B->>+I: Credentials
    I->>I: Validate credentials
    I-->>-B: Redirect: return authentication response
    B->>+E: Authentication success
    E->>E: Group/User is authorized
    E->>+S: Request access to paid content
    S->>S: Check IP address of requester<br>against registered CIDRs
    S-->>-E: Address found!<br>Send content
    E->>E: Generate WAYF-less URL
    E-->>-B: Content under WAYF-less URL
    B-->>-U: Result details
    deactivate U

Known Issues and Considerations

As observed in recent interviews with customers troubleshooting their EZProxy configurations, additional configurations might be needed to allow the cookies required by auth0 in order to provide authentication under Statista 4.0.

In addition, there are several known issues mainly related to cookies, with main sources being:

Misconfiguration of cookie filter policies
Domain issues caused by the rewriting proxy functionality

OCLC's Role

As the developer of EZProxy, OCLC provides support, maintenance, and updates to ensure seamless operation. Libraries can purchase or rent EZProxy as part of their subscription packages with OCLC. OCLC maintains so called "Stanzas" which are special instructions for the proxy that tell it how to handle certain parts of a site.

In summary, EZProxy is a web-based proxy server that enables libraries to provide Single Sign-On access to online resources for their patrons, making it easier for users to discover and access relevant content.

Additional Context

SSO Proxy Functionality

EZProxy also provides SSO proxy functionality to redirect user sessions to federated publishers' endpoints (SAML Service Providers, etc.), though this is mostly unknown and poorly exploited by institutions[^1]