LP#1413624 Docs: Move Access Handler docs to official docs
[working/Evergreen.git] / docs / admin / apache_access_handler.txt
1 Apache Access Handler Perl Module
2 ---------------------------------
3 The OpenILS::WWW::AccessHandler Perl module is intended for limiting patron
4 access to configured locations in Apache. These locations could be folder
5 trees, static files, non-Evergreen dynamic content, or other Apache
6 features/modules. It is intended as a more patron-oriented and transparent
7 version of the OpenILS::WWW::Proxy and OpenILS::WWW:Proxy::Authen modules.
8
9 Instead of using Basic Authentication the AccessHandler module instead redirects
10 to the OPAC for login. Once logged in additional checks can be performed, based
11 on configured variables:
12
13  * Permission Checks (at Home OU or specified location)
14  * Home OU Checks (Org Unit or Descendant)
15  * "Good standing" Checks (Not Inactive or Barred)
16
17 Use of the module is a simple addition to a Location block in Apache:
18
19 [source,conf]
20 ----
21 <Location /path/to/be/protected>
22     PerlAccessHandler OpenILS::WWW::AccessHandler
23     # For each option you wish to set:
24     PerlSetVar OPTION "VALUE"
25 </Location>
26 ----
27
28 The available options are:
29
30 OILSAccessHandlerLoginURL::
31   Default: /eg/opac/login +
32   The page to redirect to when Login is needed
33 OILSAccessHandlerLoginURLRedirectVar::
34   Default: redirect_to +
35   The variable the login page wants the "destination" URL stored in
36 OILSAccessHandlerFailURL::
37   Default: <unset> +
38   URL to go to if Permission, Good Standing, or Home OU checks fail. If not set
39   a 403 error is generated instead. To customize the 403 you could use an
40   ErrorDocument statement.
41 OILSAccessHandlerCheckOU::
42   Default: <User Home OU> +
43   Org Unit to check Permissions at and/or to load Referrer from. Can be a
44   shortname or an ID.
45 OILSAccessHandlerPermission::
46   Default: <unset> +
47   Permission, or comma- or space-delimited set of permissions, the user must have to
48   access the protected area.
49 OILSAccessHandlerGoodStanding::
50   Default: 0 +
51   If set to a true value the user must be both Active and not Barred.
52 OILSAccessHandlerHomeOU::
53   Default: <unset> +
54   An Org Unit, or comma- or space-delimited set of Org Units, that the user's Home OU must
55   be equal to or a descendant of to access this resource. Can be set to
56   shortnames or IDs.
57 OILSAccessHandlerReferrerSetting::
58   Default: <unset> +
59   Library Setting to pull a forced referrer string out of, if set.
60
61 As the AccessHandler module does not actually serve the content it is
62 protecting, but instead merely hands control back to Apache when it is done
63 authenticating, you can protect almost anything else you can serve with Apache.
64
65 Use Cases
66 ~~~~~~~~~
67 The general use of this module is "protect access to something else" - what that
68 something else is will vary. Some possibilities:
69
70  * Apache features
71  ** Automatic Directory Indexes
72  ** Proxies (see below)
73  *** Electronic Databases
74  *** Software on other servers/ports
75  * Non-Evergreen software
76  ** Timekeeping software for staff
77  ** Specialized patron request packages
78  * Static files and folders
79  ** Semi-public Patron resources
80  ** Staff-only downloads
81
82 Proxying Websites
83 ~~~~~~~~~~~~~~~~~
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:
87
88 [source,conf]
89 ----
90 <Location /proxy/>
91     # Base "Rewrite URLs" configuration
92     ProxyHTMLLinks  a       href
93     ProxyHTMLLinks  area        href
94     ProxyHTMLLinks  link        href
95     ProxyHTMLLinks  img     src longdesc usemap
96     ProxyHTMLLinks  object      classid codebase data usemap
97     ProxyHTMLLinks  q       cite
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
106
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
112
113     # Limit all Proxy connections to authenticated sessions by default
114     PerlAccessHandler OpenILS::WWW::AccessHandler
115
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
119 </Location>
120
121 <Location /proxy/example/>
122     # Proxy example.net
123     ProxyPass http://www.example.net/
124     ProxyPassReverse http://www.example.net/
125     ProxyPassReverseCookieDomain example.net example.com
126     ProxyPassReverseCookiePath / /proxy/example/
127
128     ProxyHTMLEnable On
129     ProxyHTMLURLMap http://www.example.net/ /proxy/example/
130     ProxyHTMLURLMap / /proxy/mail/
131     ProxyHTMLCharsetOut *
132
133     # Limit to BR1 and BR3 users
134     PerlSetVar OILSAccessHandlerHomeOU "BR1,BR3"
135 </Location>
136 ----
137
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.