INSTALL

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