Skip to page content

Athens

Minimum version required

The options described in this document require EZproxy 4.0a GA (2006-08-02) [Athens] or later. Eduserv does not support the Solaris 10 (x86), so there is not an Athens-enabled version of EZproxy available for this platform.

Overview

Athens is an Access Management system for controlling secure access to web based services. EZproxy 4.0 allows institutions that use both Athens and EZproxy to leverage Athens single sign-on access with resources provided through EZproxy. Activating the integration involves just a few, simple steps.

Registering as an Athens Data Service Provider (DSP) and for an Athens resource

To configure Athens integration, you will need to be licensed with Eduserv Athens as both an Account Management customer and a Service Provider. For organizations not supported by the JISC, this may incur a small fee. Please email the Athens Service Desk at athenshelp@eduserv.org.uk to request this.

The general download versions of EZproxy are not Athens-enabled. Athens-enabled versions of EZproxy are available for download at athens.htm . After you install or update to an Athens-enabled version of EZproxy, you can perform the following steps to enable Athens integration.

Agent configuration, client certificate and return URL

To authorize your EZproxy server to communicate with the Eduserv Athens servers, you will need to download two files from the Athens DSP Administration area. In the Download section, download the Agent 3.7 Configuration and the Client certificate (C Agent) and save both files to the directory where EZproxy is installed. The Agent 3.7 Configuration should download with the name athens_agent_conf.txt and the Client certificate (C Agent) should download with a name that is unique to your institution that matches the "CertificateFile" line of your agent configuration.

In the Athens DSP Administration area, you must also register the URL of your EZproxy server as a Return URL. In the Return URL area, enter the URL of your EZproxy server. If your server has https enabled, this should be the main https URL; otherwise, this should be the main http URL. Sample return URLs are:

Return URLConfiguration
http://ezproxy.yourlib.org:2048/Default port 2048 without any LoginPortSSL directives
http://ezproxy.yourlib.org/Use of LoginPort 80 without any LoginPortSSL directives
https://ezproxy.yourlib.org/Use of LoginPortSSL 443

Outgoing firewall configuration

Part of the Athens protocol requires that your EZproxy server be permitted to communicate directly with the servers at Eduserv. This communication normally requires that outgoing traffic to port 5055 be allowed to reach specific Eduserv servers. If your firewall configuration requires that you authorize access to specific servers, the hostnames of the Eduserv servers can be found in the athens_agent_conf.txt file in the "AuthorityServer" entries.

Routing user authentication to Athens

If all authentication should be handled by Athens, place this line in user.txt/ezproxy.usr:

::Athens

When you add ::Athens to user.txt/ezproxy.usr, all traditional EZproxy authentication is disabled.

If you will use both Athens authentication and traditional EZproxy authentication, do NOT add the ::Athens line to user.txt/ezproxy.usr, but instead add HTML similar to this to your login.htm and loginbu.htm files:

<a href="^A">Athens Users Login</a>

which will create a link from your login page to the Athens login page. For mixed authentication, be sure to review the Group statement in the sample at the end of this page to insure that your non-Athens users will retain access.

config.txt/ezproxy.cfg directives

The following directives are used in config.txt/ezproxy.cfg to activate Athens functionality in EZproxy and to associate your database definition with an Athens resource. You can click on the directives to learn more about their placement and role within an Athens configuration.

AthensDSPID YOUR_DSP_ID
AthensResource YOUR_RESOURCE_ID

The config.txt/ezproxy.cfg file allows only one AthensDSPID directive.

Most institutions will have just a single AthensResource directive which will be placed prior to the first Title directive.

Any time you change config.txt/ezproxy.cfg, you must restart EZproxy to make the change take effect.

Example configuration

This is a minimal example of an config.txt/ezproxy.cfg file for use with Athens:

Name ezproxy.yourlib.org

AthensDSPID YOUR_DSP_ID

AthensResource YOUR_RESOURCE_ID

# If you are mixing EZproxy and Athens authentication, include the following
# Group line to insure that your non-Athens users retain access
Group +Default

Title Some Database
URL http://www.somedb.com
Domain somedb.com

Advanced configurations

If you are using groups to vary the groups that are authorized to access EZproxy resources, contact support@oclc.org to discuss how to update config.txt/ezproxy.cfg to support these policies.