1 [#apache_access_handler_perl_module]
2 = Apache Access Handler Perl Module =
5 The OpenILS::WWW::AccessHandler Perl module is intended for limiting patron
6 access to configured locations in Apache. These locations could be folder
7 trees, static files, non-Evergreen dynamic content, or other Apache
8 features/modules. It is intended as a more patron-oriented and transparent
9 version of the OpenILS::WWW::Proxy and OpenILS::WWW:Proxy::Authen modules.
11 Instead of using Basic Authentication the AccessHandler module instead redirects
12 to the OPAC for login. Once logged in additional checks can be performed, based
13 on configured variables:
15 * Permission Checks (at Home OU or specified location)
16 * Home OU Checks (Org Unit or Descendant)
17 * "Good standing" Checks (Not Inactive or Barred)
19 Use of the module is a simple addition to a Location block in Apache:
23 <Location /path/to/be/protected>
24 PerlAccessHandler OpenILS::WWW::AccessHandler
25 # For each option you wish to set:
26 PerlSetVar OPTION "VALUE"
30 The available options are:
32 OILSAccessHandlerLoginURL::
33 * Default: /eg/opac/login
34 * The page to redirect to when Login is needed
35 OILSAccessHandlerLoginURLRedirectVar::
36 * Default: redirect_to
37 * The variable the login page wants the "destination" URL stored in
38 OILSAccessHandlerFailURL::
40 * URL to go to if Permission, Good Standing, or Home OU checks fail. If not set
41 a 403 error is generated instead. To customize the 403 you could use an
42 ErrorDocument statement.
43 OILSAccessHandlerCheckOU::
44 * Default: <User Home OU>
45 * Org Unit to check Permissions at and/or to load Referrer from. Can be a
47 OILSAccessHandlerPermission::
49 * Permission, or comma- or space-delimited set of permissions, the user must have to
50 access the protected area.
51 OILSAccessHandlerGoodStanding::
53 * If set to a true value the user must be both Active and not Barred.
54 OILSAccessHandlerHomeOU::
56 * An Org Unit, or comma- or space-delimited set of Org Units, that the user's Home OU must
57 be equal to or a descendant of to access this resource. Can be set to
59 OILSAccessHandlerReferrerSetting::
61 * Library Setting to pull a forced referrer string out of, if set.
63 As the AccessHandler module does not actually serve the content it is
64 protecting, but instead merely hands control back to Apache when it is done
65 authenticating, you can protect almost anything else you can serve with Apache.
68 The general use of this module is "protect access to something else" - what that
69 something else is will vary. Some possibilities:
72 ** Automatic Directory Indexes
73 ** Proxies (see below)
74 *** Electronic Databases
75 *** Software on other servers/ports
76 * Non-Evergreen software
77 ** Timekeeping software for staff
78 ** Specialized patron request packages
79 * Static files and folders
80 ** Semi-public Patron resources
81 ** Staff-only downloads
83 == Proxying Websites ==
84 One potentially interesting use of the AccessHandler module is to protect an
85 Apache Proxy configuration. For example, after installing and enabling
86 mod_proxy, mod_proxy_http, and mod_proxy_html you could proxy websites like so:
91 # Base "Rewrite URLs" configuration
93 ProxyHTMLLinks area href
94 ProxyHTMLLinks link href
95 ProxyHTMLLinks img src longdesc usemap
96 ProxyHTMLLinks object classid codebase data usemap
98 ProxyHTMLLinks blockquote cite
99 ProxyHTMLLinks ins cite
100 ProxyHTMLLinks del cite
101 ProxyHTMLLinks form action
102 ProxyHTMLLinks input src usemap
103 ProxyHTMLLinks head profile
104 ProxyHTMLLinks base href
105 ProxyHTMLLinks script src for
107 # To support scripting events (with ProxyHTMLExtended On)
108 ProxyHTMLEvents onclick ondblclick onmousedown onmouseup \
109 onmouseover onmousemove onmouseout onkeypress \
110 onkeydown onkeyup onfocus onblur onload \
111 onunload onsubmit onreset onselect onchange
113 # Limit all Proxy connections to authenticated sessions by default
114 PerlAccessHandler OpenILS::WWW::AccessHandler
116 # Strip out Evergreen cookies before sending to remote server
117 RequestHeader edit Cookie "^(.*?)ses=.*?(?:$|;)(.*)$" $1$2
118 RequestHeader edit Cookie "^(.*?)eg_loggedin=.*?(?:$|;)(.*)$" $1$2
121 <Location /proxy/example/>
123 ProxyPass http://www.example.net/
124 ProxyPassReverse http://www.example.net/
125 ProxyPassReverseCookieDomain example.net example.com
126 ProxyPassReverseCookiePath / /proxy/example/
129 ProxyHTMLURLMap http://www.example.net/ /proxy/example/
130 ProxyHTMLURLMap / /proxy/mail/
131 ProxyHTMLCharsetOut *
133 # Limit to BR1 and BR3 users
134 PerlSetVar OILSAccessHandlerHomeOU "BR1,BR3"
138 As mentioned above, this can be used for multiple reasons. In addition to
139 websites such as online databases for patron use you may wish to proxy software
140 for staff or patron use to make it appear on your catalog domain, or perhaps to
141 keep from needing to open extra ports in a firewall.