debian/README.Debian

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