Ticket Authentication

Ticket authentication is an authentication method that is often used with an existing, external authentication server to allow remote users to connect to EZproxy to access resources. With ticket authentication, a user authenticates with an authentication method, like CGI, and then the ticket script allows users authenticated with the remote server to access short-lived URLs that EZproxy will automatically recognize as being authorized to log in. This URL will permit access to a resource with no need for EZproxy to check back with the program that creates the URL within the ticket's lifetime. A sample URL looks like this:  

http://ezproxy.yourlib.org:2048/login?user=rdoe&ticket=a6911a5d0219f428b33e190a80818625%24c20041222220203%24e&url=http://www.somedb.com/

The ticket parameter on the URL contains a digital signature that EZproxy uses to verify that the URL was created by an authorized program. The ticket contains a time-stamp of when it was created, and EZproxy can be configured to determine how old a ticket can be before it is considered expired.

Ticket generating code

Sample code for generating tickets is available for ASP, Cold Fusion, Perl, and PHP. You may need to use your browser's "View Source" command to view the code behind these examples.

For assistance in adapting this sample code for use in your application or for creating similar code for other web scripting environments, contact support@oclc.org.

user.txt Example

A basic sample entry in user.txt is:

::Ticket
TimeValid 10
SHA512 somekey
Expired; Deny expired.html
/Ticket

This ticket authentication block should follow the authentication block for the external authentication server that users log in to using their authentication credentials. For example, if your institution uses CGI authentication, the CGI authentication block would come first in user.txt, and would be followed by the ticket block above.

For more details about each of these directives and the meaning, see the following section on Directives.

Directives

The following directives are specific to ticket authentication and can be used to customize your configuration in user.txt. All of these directives should fall within the Ticket authentication block:

::Ticket
#All directives and actions here
/Ticket

In addition to these directives, you may use additional actions from the Common Conditions and Actions page.

AcceptGroups

AcceptGroups is a directive used when configuring EZproxy Groups. It specifies the groups that are allowed to appear in tickets and the users who can access the resources assigned to those tickets.

Description

The following table describes how different configurations in the authentication block, both with and without AcceptGroups, would impact EZproxy's processing of user groups.

Authentication Block Result
No AcceptGroups included Any groups specified in the ticket are ignored.
AcceptGroups is included, but the ticket does not contain any groups The user is assigned to a group based on the last Group directive that was processed.

The user is assigned to the Default group if no previous Group directive was processed.
AcceptGroups is included, and the ticket contains groups The user is assigned to the groups specified in the ticket that are also allowed by AcceptGroups.

Qualifiers

The following qualifiers must be added after AcceptGroups to define the user groups in a ticket.

Qualifier Description
group The name of a group that should be allowed to appear in tickets.

Example

This directive must appear before any directives specifying the shared key (e.g. MD5, SHA1, SHA256, and SHA512).

The following example would allow the groups Default, Law, or Medical to appear in a ticket: 

::Ticket
AcceptGroups Default+Law+Medical
SHA512 secretkey
IfUnauthenticated; Stop
/Ticket

MD5, SHA1, SHA256, SHA512

MD5, SHA1, SHA256 and SHA512 are directives that specify the cryptographic hashing algorithm that should be use to validate tickets. The directive should be followed by the shared key that should be used to validate tickets. The shared key entered with this directive in user.txt must match the key specified in the ticket generating script.

If the shared key is compromised, any external system can use the shared key to generate a ticket to authorize a user to have access to EZproxy. If this occurs, the shared key should be changed to a new value in the external system and in user.txt.

Qualifiers

Qualifier Description
sharedkey The key shared between the ticket creating software and EZproxy to authenticate.

Examples

The following table shows examples of each directive in the context of a Ticket authentication block.

Directive Version Example
MD5 V5.2 or later ::Ticket
TimeValid 10
MD5 md5key
Expired; Deny expired.html
/Ticket
SHA1 V5.2 or later ::Ticket
TimeValid 10
SHA1 sha1key
Expired; Deny expired.html
/Ticket
SHA256 V6.1 or later ::Ticket
TimeValid 10
SHA256 sha256key
Expired; Deny expired.html
/Ticket
SHA512 V6.1 or later ::Ticket
TimeValid 10
SHA512 sha512key
Expired; Deny expired.html
/Ticket

TimeOffset

TimeOffset is a directive that specifies the number of minutes to add or subtract to the time value included in a ticket before comparing that time to the clock on the EZproxy server. This is often used to adjust the time to account for time zone differences. These differences can occur and limit remote users' ability to access resources when a ticket is generated with a time specified in local time format on a server in a different time zone than the EZproxy server.

Qualifiers

Qualifier Description
minutes The number of minutes to add or subtract from the time value included in the ticket. To indicate subtraction, specify a negative number.

Examples

This directive must appear before the MD5, SHA1, SHA256 or SHA512 directive. The following table shows how to add or subtract time from the time value specified in the ticket.

Time Change user.txt Example
Add 60 minutes to the time specified in the ticket. ::Ticket
TimeOffset 60
SSHA256 secretkey
IfUnauthenticated; Stop
/Ticket
Subtract 2 hours (120 minutes) from the time specified in the ticket. ::Ticket
TimeOffset -120
SSHA256 secretkey
IfUnauthenticated; Stop
/Ticket

TimeValid

TimeValid is a directive that specifies the window of time in minutes for which a ticket should be considered valid. This window will begin at the time specified in the ticket. For example, if the ticket has a time stamp of 1:00pm EST, and the TimeValid is set to 30, that ticket will provide a remote user with access until 1:30pm EST. If there is no TimeValid directive within the authentication block, the default value of 60 minutes is used.

TimeValid can be used to compensate for time variations between the ticket generating system and EZproxy clocks. A larger window is useful if the external system generates a page of ticket URL links that is intended to remain valid for use for an extended period of time.

Qualifiers

Qualifier Description
minutes The number of minutes that a ticket should be considered valid.

Examples

This directive must appear before the MD5, SHA1, SHA256 or SHA512 directive.

The following example will reduce the time a ticket is valid from the default of 60 minutes to 5 minutes.

::Ticket
TimeValid 5
SHA256 secretkey
/Ticket

 

 

Groups

If you want to include groups as part of your tickets, you must tell EZproxy which groups are allowed to appear in tickets with the AcceptGroup directive. Sample usage is:

::Ticket
AcceptGroups General+Medical+Legal
TimeValid 10
MD5 somekey
Expired; Deny expired.html
/Ticket

In this example, a ticket can include any combination of the three groups specified, but any attempt to place the user in any other groups would be ignored.

This page last revised: September 23, 2015