CGI Authentication

The following method describes how to reroute all user interaction for EZproxy authentication to your own script. With CGI authentication, you are responsible for all user interaction, including collecting credentials, validating them, and returning the user to EZproxy. See also External Script Authentication for a simpler method that allows you to provide your own script for validating credentials without being required to handle all user interaction.

To provide your own custom user authentication handling, follow these steps:

Edit the
  1. Edit your user.txt/ezproxy.usr file and add a line like:
    ::CGI=http://auth.yourlib.org/ezpauth.cgi?url=^R
    OR
    ::CGI=http://auth.yourlib.org/ezpauth.cgi?url=^U

    This line indicates that when a user needs to be authenticated, EZproxy should redirect the user to a script that is available at http://auth.yourlib.org/ezpauth.cgi.

    If you choose the form that ends in url=^R, then EZProxy will provide an opaque string that represents the original URL requested. This is the simplest form to use as it avoids the use of special characters such as ampersands (&).

    If you choose the form that ends in url=^U, then EZproxy will provide the original URL requested in a URL escaped format, where special characters such as ampersands (&) will be replaced by a %xx format such as %26.

    After CGI=, you may specify a URL that starts with https instead of http if your authentication script is installed on a secure web server.

    user.txt/ezproxy.usr will need additional entries to allow the Ticket URL to be recognized and accepted.

  2. Once the user is redirected to the custom script, the script can authenticate the user in any manner you choose. During authentication the value provided by the url query string variable must be preserved so it can be returned to EZproxy when the user has been authenticated.
  3. Assuming that the script authenticates the user, the script then construct a return URL using Ticket Authentication to return the user back to the EZproxy server. The Ticket URL must be constructed to include the url value originally provided when the user was redirected to the custom script.

Data flow

The exact data flow used in performing CGI authentication is documented on a separate web page at CGI Authentication Data Flow

Groups

Normally, when your custom CGI script sends the user back to EZproxy with a Ticket URL, the Ticket URL should indicate all groups for which the user should be authorized for access. If you want to handle inadequate group access separately, your entry in user.txt/ezproxy.usr can look like this:

::CGI=http://auth.yourlib.org/ezpauth.cgi?url=^U&logup=^L

The ^L will be replaced by "true" if the user is trying to access a resource outside of group assignment and "false" during an initial authentication. This version demonstrates the use of url=^U to provide the original URL requested. Your script may be able to use this information along with a value of "true" for logup to determine a particular course of action when giving the user feedback that access is unavailable.