CGI Authentication Data Flow

You may want to print a copy of this diagram as it is referenced by the following.

The diagram describes the flow of data during an EZproxy login that involves external CGI authentication. In this document and on the diagram, "ezproxy" is used as the host name for your EZproxy server, "CGI" is the name of your CGI server, "db" is the remote database vendor, "script" is your CGI script, and "s" (as in http://db/s) is the starting page portion of the URL the user is trying to reach.

Also, ezproxy:2 represents the login port on EZproxy (normally ezproxy:2048), and ezproxy:3 represents the virtual web server created for the "db" host.

In EZproxy, you would set up this link by editing ezproxy.usr and adding a line like this:

::CGI=http://cgi/script?url=^R
::Ticket
TimeValid 1
MD5 verysecret
Expired; Deny expiredticket.htm
/Ticket

The first line tells EZproxy that authentication requests should be rerouted to http://cgi/script with a query string parameter named url which will receive an opaque representation of the destination URL (e.g., http://db/s is not passed to the CGI script, but instead a string of letters, digits, numbers, and select special characters which represents the destination URL).

The subsequent lines are typical of configuration for a ticket URL. A ticket URL is the mechanism used to return an authenticated user to EZproxy for access. More information on ticket URLs appears at Ticket Authentication .

Your CGI script is involved in lines 3 - 6. It is automatically brought into the loop by EZproxy when unauthenticated users attempt access. After a user has been authenticated, it is no longer involved in the process.

Here is a detailed description of what happens during each step.

  1. We start with the assumption that the user just clicked a link to http://ezproxy:2/login?url=http://db/s. This link may have been on any web server anywhere, and would typically come from a page that has links to all of your database vendors from somewhere in your libraries home page.
  2. EZproxy has identified that the user is not yet authenticated, so it reroutes the use to your CGI script, sending an opaque string of letters, digits, hyphen (-), underscore (_), and/or periods (.) that represents the URL the user was trying to reach.
  3. The user's browser goes straight to your CGI script, with the user not having noticed anything has really happened.
  4. Your CGI script sends back a form for the user to complete for validation. This form contains a hidden field url that your CGI program will use later as it completes the authentication process, allowing your user to continue on to the resource originally requested.
  5. The user has filled out the form, and now the user submits the form for processing.
  6. Your CGI script has successfully authenticated the user (if not, you might go back to line 4 to send the CGI form again, along with appropriate error message). Since the user authenticated, your CGI script generates a ticket URL to authenticate the user into EZproxy. The ticket URL contains the username to associate with the user, a cryptographic signature to prove authentication, and the opaque version of the URL of the database the user is trying to reach. More information on generating ticket URLs can be found at Ticket Authentication .
  7. The browser sends the ticket URL to the EZproxy server .
  8. EZproxy creates a new session and routes the user back to complete session setup.
  9. The browser returns to confirm session setup .
  10. EZproxy sends back the right response to embed a cookie in the user's browser as an ongoing indication that the user has validated, along with a redirect to come back to EZproxy to verify that the cookie embedded correctly.
  11. EZproxy verifies that the cookie is present. If it is missing, the file cookie.htm is sent from the docs subdirectory.
  12. The user's cookie was present, so EZproxy now redirects the user to the EZproxy virtual web server to begin remote access.
  13. The user's browser requests the "/s" page from the virtual web server.
  14. EZproxy forwards the request on to the real server.
  15. EZproxy receives back the response from the remote database server.
  16. EZproxy edits the response, then sends it back to the user.