docs/RELEASE_NOTES_NEXT/Administration/apache_access_handler.txt

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