Common Conditions and Actions

Minimum version required

The features described in this document require EZproxy 5.0b GA or later.

Overview

In EZproxy 4.0, the common conditions and actions shared by extended authentication and authorization methods were standardized. These common conditions and actions can be combined with the specific conditions and actions of authentication and authorization methods such as LDAP to create authorization rules that determine which users are allowed to access EZproxy and which resources within EZProxy those users may use.

Wildcard and Regular Expression comparisons

Within conditions, if the compare text starts with wild, then the comparison defaults to a case-insensitive match allowing * to match 0 or more characters and ? to match any one character.

You can add -CS before the comparison text to make the comparison case-sensitive.

You can specify that the comparison should use a regular expression by adding -RE in front of the comparison text. If you specify -RE but not -CS, be aware that the comparison text will be converted to lower-case, but the regular expression will not be changed, so all literal text in the regular expression should be specified in lower-case or else it will not match.

Conditions

IfAfter yyyy-mm-dd

True if the current date is on or after the date specified.

IfAuth wildauth

True if the URL used to access EZproxy include an "auth=value" string where the value matches the wildauth. You can specify just IfAuth with no wildauth to test if there was no "auth=value" specified.

IfAuthenticated

True if the user successfully authenticated to the remote server and the user's account is not expired.

IfBefore yyyy-mm-dd

True if the current date is before (but not the same as) the date specified.

IfCity wildcity

True if one or more Location directives appear in config.txt/ezproxy.cfgthat map the city associated with the user's IP address to match wildcity.

IfCountry wildcountry

True if one or more Location directives appear in config.txt/ezproxy.cfgthat map the country code associated with the user's IP address to match wildcountry. Country codes should be specified using two-character extended ISO 3166 codes.

IfDay day[,day...]

True if the current day matches one of the day values. The day can either by a number 1 to 31 to represent a day of the month or a day of the week specified as SUnday, Monday, TUesday, Wednesday, THursday, Friday, SAturday where the capitalized text is the shortest abbreviation you can use for a day of the week (e.g., SU is the shortest for Sunday, M is the shortest for Monday, etc.)

IfExpired

True if the user's account has expired.

IfGroupMember group1[+group2...]

True if the user is a member of any of the groups specified.

IfHeader header:wildvalue

True if the incoming request from the client has a header that matches the wildvalue. If you omit the : or include it but omit wildvalue, true if there are no headers of the specified type in the request.

IfHttp

True if the incoming request is using http.

IfHttps

True if the incoming request is using https.

IfInvalid

True if EZproxy was able to connect to the authentication server and the username or password was not correct.

IfIP ip[-ip][;ip[-ip]...]

True if the remote user's IP address matches one of the individual IP addresses specified or falls within a specified range.

IfLanguage wildlanguage

True if the browser's "Accept-Language" header matches wildlanguage.

IfMonth month[,month...]

True if the current month matches one of the month values. The month can either by a number 1 to 12 or it can be a minimum of three letters of the month name (e.g., 1, Jan, and January all match the January).

IfNoGroups

True if the user is not a member of any EZproxy groups.

IfPassword wildpassword

This condition appeared in EZproxy 4.0b GA (2006-08-18). True if the password that the user is attempting to log in with matches the wildpassword. The wildpassword can contain the * wildcard to match 0 or more characters and the ? wildcard to match exactly one character.

IfReferer wildreferer

True if the incoming referring URL matches wildreferer.

IfRegion wildregion

True if one or more Location directives appear in config.txt/ezproxy.cfgthat map the region code associated with the user's IP address to match wildregion. Region codes should be specified using the two-character ISO 3166-2 subcountry code for the US and Canada or the FIPS 10-4 subcountry code for other regions of the world.

IfRefused

True if the authentication server refused EZproxy's attempt to connect, most commonly due to the remote server being down.

IfTime start-end[,start-end...]

True if the current time of day is on or after start and is on or before end. A time should be written as hour[:minute][(am|pm)] where it must start with an hour, may be followed by a colon (:) and minute, and may optionally include am or pm. If the minute is omitted it defaults to 0. If am and pm or omitted, military time is assumed. An end-time of 59 minutes of the hour matches completely to the end of the hour, such as 10pm-11:59pm will match everything starting at 10pm until but not including midnight.

IfUnauthenticated

True if the user has not successfully authenticated to the remote server, including instances where the authentication server is unavailable (IfRefused), the user's password was incorrect (IfInvalid), and the user's access is expired (IfExpired).

IfURL wildurl

True if the destination URL of a starting point URL matches wildurl.

IfUser wildusername

True if the username that the user is attempting to log in with matches the wildusername. The wildusername can contain the * wildcard to match 0 or more characters and the ? wildcard to match exactly one character.

IfUsrVar # wildvalue

True if the user variable # (values 0 through 9) that was set by UsrVar matches wildvalue.

IfYear year[,year...]

True if the current year matches on the specified years. Year can be specified as either 2 or 4 digits.

Actions

Admin

Grant the current user administrative access to EZproxy. This directive should always be combined with appropriate conditions to select only administrative users. If this directive appears alone on a line, all users can be declared administrators. If using Admin with either of the Expression functions UserFile or UserString, refer to the UserFile documentation for information on how Admin interacts with these functions.

Audit [-expr] other

Record an Audit event of type Info.usr with the text other recorded in the Other column. In Ezproxy 5.1b or later, if the -expr qualifier is included, then other is evaluated as an Expression and the resulting value is recorded.

Allow

Allow appeared in older versions of EZproxy. It still works, but it has been replaced by Stop which provides equivalent functionality but better reflects what happens when it is encountered.

Banner filename.html

Send filename.html from the docs subdirectory to the user after login completes but before the user is routed to the destination database. The banner file must contain a link like:

<a href="^C">continue to resource</a>

to allow the user to move on to the destination resource.

Debug

Record additional information regarding the login process to messages.txt/ezproxy.msg. This can include copious amounts of information and sensitive information, so Debug should only be applied when initially configuring an authentication method and to diagnose problems, after which it should be removed.

Deny [-NoAudit] filename.html

Deny access for the remote user and send filename.html from the docs subdirectory to explain why access is denied. If filename.html is omitted, the default file is deny.htm. In EZproxy 5.1b or later, a Login.Denied Audit event is recorded if auditing is enabled unless the -NoAudit qualifier is included.

Deny [-NoAudit] -Redirect http://www.yourlib.org/denypage.html

Deny access for the remote user and redirect the user to the specified URL. In EZproxy 5.1b or later, a Login.Denied Audit event is recorded if auditing is enabled unless the -NoAudit qualifier is included.

DocsCustom dir

DocsCustom allows you specify an alternate directory that EZproxy should check first when it looks for files that are normally found in the docs subdirectory. DocsCustom directs EZproxy to first look in the docs subdirectory for a directory named custom, and within the custom directory, EZproxy look for dir, and within that directory, EZproxy looks for the file. For example, when EZproxy looks for menu.htm, it would first look for docs/custom/ dir/menu.htm and if it couldn't find that file then it will use docs/menu.htm.

Group [+|-]group1[[+|-]group2...]

Add or remove the user from groups. Individual groups are separated by + and -. If there is not a + or - in front of group1, all existing groups are removed from the user and group1 is assigned to the user. When a group name is preceded by +, the group is added to the user's authorized groups. When a group name is preceded by -, the group name is removed from the user's authorize groups.

You can follow Group with the special value NULL to remove the user from all groups.

Ignore

Ignore on a line by itself has no affect. When used as an action with the IfExpired condition, indicates that expired user should be considered valid; when used as an action with the IfRefused condition, indicates that the system should treat the remote user as though their information was valid.

Msg [-expr] message

This directive can be used to record arbitrary message into the messages.txt/ezproxy.msg file. If the -expr qualifier is included, then message is evaluated as an Expression and the resulting value is recorded.

Stop

Stop processing directives from this authentication method. If the user is allowed access by the directives that lead up to this directive, the user will be granted access. If the user is not allowed access, skip the rest of the statements for the current authentication method and move to the next part of user.txt/ezproxy.usr.

Unknown

Consider the user to be an unknown user, even if the user had authenticated, had expired access, or the remote server was down. Unknown has includes an implicit Stop; once encountered, no further processing occurs for the current authentication method.

UsrVar #   value

EZproxy has ten user variables available to receive values, numbered 0 through 9. You can assign a value to a user variable by providing the digit of the variable for # and the value in value. To erase a variable, leave the value section blank. The user variables can be tested with IfUsrVar and can also available for log recording in LogFormat and LogSPU.

GeoLite data

This product includes GeoLite data created by MaxMind, available from www.maxmind.com .