debian/README.Debian

   1 libapache2-mod-vhost-ldap and LDAP server support
   2 =================================================
   3
   4 Your LDAP server needs to include mod_vhost_ldap.schema. If You want
   5 additional access control, then include apache_ext.schema also.
   6 If you do not use OpenLDAP you are on your own to build a schema.
   7 I used these lines:
   8
   9 index   apacheServerName,apacheServerAlias,apacheDocumentRoot,apacheServerAdmin pres,eq
  10 index   apacheExtConfigUri,apacheExtConfigServerName pres,eq,sub
  11 index   apacheLocationOptionsDn,apacheExtConfigRequireValidUser,apacheExtConfigUserDn,apacheExtConfigUserServerName,apacheExtConfigObjectName pres,eq
  12
  13  -- Piotr Wadas <pwadas@jewish.org.pl> Fri 31 Mar 2006 20:00:08 +0100
  14
  15 You should configure the LDAP server to maintain indices on apacheServerName,
  16 apacheServerAlias and anything you use in your additional search filter.
  17
  18  -- Ondřej Surý <ondrej@sury.org>  Tue, 30 Aug 2005 15:25:32 +0200
  19
  20 libapache2-mod-vhost-ldap, suexec and cgid
  21 ==========================================
  22
  23 libapache2-mod-vhost-ldap suexec support doesn't work with cgid (enabled
  24 as default in Debian).  Cgid has special hacks for suexec module and any
  25 other module which set suexec uid and gid crashes mod_cgid. For more
  26 information see http://issues.apache.org/bugzilla/show_bug.cgi?id=36410
  27
  28 You can use cgi module instead.
  29
  30  -- Ondřej Surý <ondrej@sury.org>  Tue, 30 Aug 2005 09:24:21 +0200
  31
  32
  33 Just run "make" to build the module and "make install" (as root) to install
  34 the module. This will use Apache's apxs to build/install from source.
  35
  36 Have a look at vhost_ldap.conf to learn about configuration.
  37
  38 Authentication and authorization works in the following way:
  39
  40 1. Vhost configuration is checked in ldap
  41 At this step all requested attributes such as ServerName, ServerAlias etc.
  42 including apacheExtConfig attributes, are taken. If not - vhost is returned
  43 OK and goes after further request processing.
  44
  45 2. If vhost has set
  46 apacheExtConfigHasRequireLine = TRUE, AND AT LEAST ONE apacheLocationOptionsDn
  47 is set pointing to apacheExtConfig object, vhost is marked to have auth/auth.
  48
  49 3. Then request URI is checked - starting from /, if for URI or any of
  50 URIs below apacheExtConfigObject with apacheExtUri set for uri, is found below
  51 base dn set with VhostLDAPWebLocationConfigBaseDn, processing to generate
  52 require lines. Note, that whatever apacheExtConfigObjectName You set
  53 for configuration, it will appear on authentication dialog box as You'd
  54 specify it with AuthName directive. AuthType (basic) is in code.
  55
  56 4. if apacheExtConfigRequireValidUser for matched extConfig object is
  57 set to TRUE, then "require valid-user" is generated.
  58 if apacheExtConfigRequireValidUser is set to FALSE, then
  59 there's another search performed, under webUsersbase, to find user names,
  60 for which apacheExtConfigUserServerName matches vhost original name.
  61 All usernames are appended for require line, which contains at least no-user
  62 "nobody",
  63 if no user objects are found. so after, we have
  64 require valid-user
  65 or
  66 require nobody username1 username2
  67 placed into apache config
  68
  69 5. authentication phase - user password is checked with LDAP. Note, that
  70 it's checked agains two conditions - with apr_validate_password, and with clear
  71 text. So, in userPassword field, You can put password taken from .htaccess file
  72 (or generated with htpasswd -n), or clear text, and it will be matched agains
  73 string comparison.
  74
  75 6. Then, authorization phase - if for current URI on previously generated
  76 require line, basic-auth username is found, then access is granted.
  77
  78 7. In log You shoud have information, whether authentication is successed or
  79 failed, and then information _ONLY_ if authorization denies access.
  80 (authorization access granted is not logged, don't ask why :)
  81
  82 MORE EXPLANATION:
  83 object of one of apacheExt* classess, have some dn-syntax attributes, which
  84 should point like below:
  85
  86 *       one or more apacheLocationOptionsDn     |       for vhost,
  87                                                                                         pointing location config(s)
  88
  89 *       one or more apacheExtConfigUserDn       |       for location config,
  90                                                                                         pointing user object(s)
  91
  92 However this is for use with some external management GUI to keep track of
  93 what's going on - search is made for location on vhost level, and search is
  94 made for users on location level, because apr doesn't have convenient routines,
  95 which allows getting object directly based on its DN. So final result
  96 must be FOUND, not GET, and is found based on another attribute value,
  97 eg. apacheExtConfigServerName for location config,
  98 and apacheExtConfigUserServerName This should be
  99 implemented with ldap.h, or routines for apr should be created.
 100
 101 IMPORTANT NOTE 1:
 102 All searches for users, and location configurations, are made with
 103 apacheServerName attribute value of current vhost - no matter via which
 104 alias You're accessing server. So YOU DON'T NEED TO ADD EACH serverAlias
 105 to UserObject, or configObject - just add serverName.
 106 The concept is, that when You want to block some resource, eg. some
 107 directory with Your pictures, You want it blocked for all aliases on current
 108 server, no matter how it's access. If You share the same directory under
 109 another vhost, you need to add this vhost serverName to location
 110 extConfigServerName.
 111
 112 IMPORTANT NOTE 2:
 113 Authentication and authorization with this module is dynamic, that's
 114 why advanced features like apache configstream are not used. Actually
 115 auth/authz information is build against each request, to make You able
 116 to manipulate access control information, without server restarting
 117 (even graceful). Actually making graceful, is no problem - the point is,
 118 that if You edit Your LDAP with some external tool,
 119 e.g. excellent phpldapadmin, You may not want this tool to execute or force
 120 (in any way) any kind of daemons restart. Another solution, is to put
 121 graceful into cron somewhere, however I guess dynamic access control
 122 is more ee.., well, its better solution :)
 123
 124 IMPORTANT NOTE 3:
 125 If Your changes in LDAP seems to not working, check some cacheTTL and
 126 other directives with apache ldap_module, You've read this module manual,
 127 didn't You? :)
 128
 129
 130 TIPS and HINTS:
 131 Enjoying LDAP power - You can have multiple values for some attributes.
 132 actually no matters how many values You set for apacheLocationOptionsDn
 133 (must be at least one), because search is made with uri and serverName.
 134
 135 However, You can set more than one serverName with location object,
 136 if You want the have the same URI blocked on more than one webserver,
 137 eg. if Your vhosts has standard location "/statistics", You can
 138 block them for all vhosts you want, no matter, whether real statistics
 139 dir exists in filesystem, or not (auth/authz is made before returning data).
 140 Anyway defining the same location for different vhosts as separated object
 141 should work, however they should have different naming attribute.
 142 If You set two objects, for the same uri and different naming attribute, and
 143 the same vhost servername value, probably the first one found will be used,
 144 I didn't check.
 145 extConfigObject may also apply to more than one URI - the same.
 146 You can also have the same user, valid for more than one vhost, exactly
 147 the same rules apply like above.
 148 One user can have more than one password.
 149
 150 Actually defining separate objects, makes sens only if
 151 You want to be able to quickly enable/disable particular URI
 152 (or user, or config, etc. etc.), instead of removing it, probably
 153 based on some attribute value defined elsewhere, and applied to ldap filter
 154 in mod-ldap-vhost configuration.
 155
 156 DEVELOPER's NOTE:
 157 The main trick is, that ap_requires is used to SET requirelines using generated
 158 apr_array_header_t, based on some information source, before it's later used
 159 in normal authz procedure, at appropriate authorization hook.
 160
 161 TODOs (unsorted):
 162 * general code review (use of per-directory-config ?)
 163 * implement php_admin_flag and php_admin_value setting for vhosts with ldap
 164 * implement directory access control, similar to location
 165 * implement directory/location aliasing between vhosts, based on ldap
 166 * implement logging-related directives for ldap-based vhosts
 167 * implement require group
 168 * implement use of other authentication methods than basic, including X509,
 169 and authentication based not only with apacheExtUserObject, but also with
 170 classic posixAccount/Group, probably with use of other excellent modules
 171 like mod_authz_ldap and others..
 172 * testing with apache 2.2.x
 173
 174 * testers are welcomed, probably some nullpointer and overflows possibility
 175 extists, anyway Apache The Greate works holds the line - I tested some
 176 generated module segfaults, and they doesn't break apache itself, module only.