How to create EZproxy stanzas for passworded resources

We now use EZproxy to provide access to all of our e-resources that have their own local, generic usernames/passwords (in addition to IP-authenticated e-resources – the ‘traditional’ use of EZproxy).

These resources are usually not ‘standard’ academic journals or databases – they tend to be specialist professional/business resources, magazine websites, and journals from small publishers.

This whole process is quite hack-y, and we rely on trial and (a lot of) error to create, test and tweak the EZproxy stanza for each resource. I’m indebted to advice I got on the EZproxy mailing list and from colleagues in ICT Services at Lincoln.

There are two basic methods of creating stanzas for passworded resources. For either method to work, the EZproxy installation must be using ‘Proxy by Hostname’, not the less-common ‘Proxy by Port’.

In both methods, we use Google Chrome Developer Tools to inspect the HTML of the resource’s login page. I’m told it’s also possible to do this using Firefox web developer tools. (I have no idea about IE.)

I’ve highlighted HTML elements (tags/attributes) in red.

Method #1 – the “FormVariable” method

You should use this method if you can. It’s easier to create these stanzas, it will work for the majority of resources, it should be faster for the end-user, and it’s a lot less brittle (i.e. less likely to break) than method #2 below.

However it won’t work with resources that rely on ASP.NET __VIEWSTATE or Ajax for their login method. Also, it does end up creating weird, local login URLs for the resources instead of ‘normal’ EZproxy login URLs – this means we have to set up special URL-rewriting templates in our link resolver for these resources.

Here’s how to use it:

  1. Navigate to the login page for the resource (i.e. a page with a username/password box).
  2. In Google Chrome, right-click on the login box and select “Inspect element”.
  3. From the login form, pick out the following elements:
    • The value of the method attribute in the form tag (usually this = post).
    • The value of the action attribute in the form tag (this will be a URL. If it is expressed as a relative URL, you will need to covert it into an absolute URL).
    • For every input tag within the form, the value of its name element. There will usually be at least two input tags within the form (one each for username and password); there will often be more. Record them all, except for any input tags where type=”submit”.
  4. You also need to invent a short, arbitrary ‘slug’; a text identifier for the resource.
  5. Now construct an EZproxy stanza like this:
Title (The name of the resource)
URL -Form=value_of_form_method_attribute (slug) value_of_form_action_attribute
FormVariable value_of_input_name_attribute_1=XXXXXX
FormVariable value_of_input_name_attribute_2=YYYYYY
FormVariable value_of_input_name_attribute_3=ZZZZZZ

etc, repeating “FormVariable” as many times as necessary. XXXXXX, YYYYYY, and ZZZZZZ are the end-values you want to plug into your form inputs – i.e. your username, password, and any other input elements.

An (imaginary) example would look like:

Title Journal of Advanced Stuff and Things
URL -Form=post jnlasat http://www.journal-ast.org/login.php
FormVariable userName=unioflincoln
FormVariable passWord=password123
FormVariable rememberMe=false
FormVariable referringURL=http://www.journal-ast.org/home.php

The login URL that EZproxy then creates for the resource will be in the following format:

A real-world example from the University of Lincoln:

You need to remember that if your link resolver / journals software has a URL-rewriting facility (sometimes described as a “proxy mask“) to send all links via EZproxy, you may need to create special rules for these non-standard URLs.

Method #2 – the “Find/Replace” method

The second method works by EZproxy identifying and rewriting parts of the page HTML, with JavaScript used to automate the form submission.

This method is trickier to set up, tends to be slower for the end-user, and is more brittle (i.e. more likely to break) than method #1. However it will work with (some) resources that rely on ASP.NET __VIEWSTATE or Ajax for their login method.

Its saving grace is that it creates more ‘normal’ resource login URLs, but if you use ExcludeIP statements in your EZproxy config file to simplify on-campus traffic, you may need to quarantine these “Find/Replace” resource stanzas and treat them differently from purely IP-authenticated resources.

Here’s how to use it:

  1. Navigate to the login page for the resource (i.e. a page with a username/password box).
  2. Make a note of the login page URL.
  3. In Google Chrome, right-click on the login box and select “Inspect element”.
  4. From the login form, pick out the following elements:
    • The entire input element (opening tag plus all attribute-value pairs) for the username input, up to but not including the value attribute. This will look something like:
      • <input attribute_1=”value_1″ attribute_2=”value_2″ attribute_3=”value_3″
    • The entire input element, as above, for the password input. We’ll refer to this as:
      • <input attribute_4=”value_4″ attribute_5=”value_5″ attribute_6=”value_6″
    • For the input tag where type=”submit”, record the value of the id attribute. If this tag doesn’t have an id attribute, it’s possible to use its name attribute instead, but you’d need to construct a different (and slightly more complicated) stanza to the one below.
  5. Now construct an EZproxy stanza like this:
Title (The name of the resource)
URL (The URL of the login page for the resource)
Find <input attribute_1=”value_1″ attribute_2=”value_2″ attribute_3=”value_3″
Replace <input attribute_1=”value_1″ attribute_2=”value_2″ attribute_3=”value_3″ value=”XXXXXX
Find <input attribute_4=”value_4″ attribute_5=”value_5″ attribute_6=”value_6″
Replace <input attribute_4=”value_4″ attribute_5=”value_5″ attribute_6=”value_6″ value=”YYYYYY
Find </form>
Replace </form>document.getElementById(‘value_of_input_id_attribute‘).click();
Host (The domain of the resource, including www if present)

XXXXXX is the resource username, and YYYYYY is the password. The login URL it creates will be a standard-format EZproxy URL, i.e. http://(yourproxydomain)/login?url=(resource_url)

Remember that if you use ExcludeIP statements in your EZproxy config file to simplify on-campus traffic, you may need to quarantine these “Find/Replace” resource stanzas and treat them differently from purely IP-authenticated resources.

That’s it!

Here’s a list of current resources for which we’re using one or the other of these methods. I’m happy to share our stanzas (with usernames and passwords redacted, obviously). Just email me.

Method #1 (“FormVariable”)

  • BRAD Insight
  • CABI Leisure Recreation and Tourism Abstracts (www.cabdirect.org)
  • Campaign magazine (BrandRepublic)
  • Campden BRI
  • Children & Young People Now magazine
  • Fresh Produce Journal
  • Frieze magazine
  • Leisure Management magazine
  • IHS Technical Indexes
  • Media Lawyer – Press Association
  • PR Week magazine (BrandRepublic)
  • Thomson Reuters IDS
  • TRADA (Timber Research and Development Association)

Method #2 (“Find/Replace”)

  • Equal Opportunities Review
  • Ethical Space
  • Food Technology
Advertisements