X-Git-Url: http://andersk.mit.edu/gitweb/mod-vhost-ldap.git/blobdiff_plain/7f9875bb3e8210122b73b7a63644d039733d04d6..refs/heads/ext-config/debian:/INSTALL diff --git a/INSTALL b/INSTALL index 59d42e5..3f61ebe 100644 --- a/INSTALL +++ b/INSTALL @@ -3,8 +3,147 @@ the module. This will use Apache's apxs to build/install from source. Have a look at vhost_ldap.conf to learn about configuration. -Your LDAP server needs to include mod_vhost_ldap.schema. If you do not use -OpenLDAP you are on your own to build a schema. +Your LDAP server needs to include mod_vhost_ldap.schema. If You want +additional access control, then include apache_ext.schema also. +If you do not use OpenLDAP you are on your own to build a schema. You should configure the LDAP server to maintain indices on apacheServerName, apacheServerAlias and anything you use in your additional search filter. + +Authentication and authorization works in the following way: + +1. Vhost configuration is checked in ldap +At this step all requested attributes such as ServerName, ServerAlias etc. +including apacheExtConfig attributes, are taken. If not - vhost is returned +OK and goes after further request processing. + +2. If vhost has set +apacheExtConfigHasRequireLine = TRUE, AND AT LEAST ONE apacheLocationOptionsDn +is set pointing to apacheExtConfig object, vhost is marked to have auth/auth. + +3. Then request URI is checked - starting from /, if for URI or any of +URIs below apacheExtConfigObject with apacheExtUri set for uri, is found below +base dn set with VhostLDAPWebLocationConfigBaseDn, processing to generate +require lines. Note, that whatever apacheExtConfigObjectName You set +for configuration, it will appear on authentication dialog box as You'd +specify it with AuthName directive. AuthType (basic) is in code. + +4. if apacheExtConfigRequireValidUser for matched extConfig object is +set to TRUE, then "require valid-user" is generated. +if apacheExtConfigRequireValidUser is set to FALSE, then +there's another search performed, under webUsersbase, to find user names, +for which apacheExtConfigUserServerName matches vhost original name. +All usernames are appended for require line, which contains at least no-user +"nobody", +if no user objects are found. so after, we have +require valid-user +or +require nobody username1 username2 +placed into apache config + +5. authentication phase - user password is checked with LDAP. Note, that +it's checked agains two conditions - with apr_validate_password, and with clear +text. So, in userPassword field, You can put password taken from .htaccess file +(or generated with htpasswd -n), or clear text, and it will be matched agains +string comparison. + +6. Then, authorization phase - if for current URI on previously generated +require line, basic-auth username is found, then access is granted. + +7. In log You shoud have information, whether authentication is successed or +failed, and then information _ONLY_ if authorization denies access. +(authorization access granted is not logged, don't ask why :) + +MORE EXPLANATION: +object of one of apacheExt* classess, have some dn-syntax attributes, which +should point like below: + +* one or more apacheLocationOptionsDn | for vhost, + pointing location config(s) + +* one or more apacheExtConfigUserDn | for location config, + pointing user object(s) + +However this is for use with some external management GUI to keep track of +what's going on - search is made for location on vhost level, and search is +made for users on location level, because apr doesn't have convenient routines, +which allows getting object directly based on its DN. So final result +must be FOUND, not GET, and is found based on another attribute value, +eg. apacheExtConfigServerName for location config, +and apacheExtConfigUserServerName This should be +implemented with ldap.h, or routines for apr should be created. + +IMPORTANT NOTE 1: +All searches for users, and location configurations, are made with +apacheServerName attribute value of current vhost - no matter via which +alias You're accessing server. So YOU DON'T NEED TO ADD EACH serverAlias +to UserObject, or configObject - just add serverName. +The concept is, that when You want to block some resource, eg. some +directory with Your pictures, You want it blocked for all aliases on current +server, no matter how it's access. If You share the same directory under +another vhost, you need to add this vhost serverName to location +extConfigServerName. + +IMPORTANT NOTE 2: +Authentication and authorization with this module is dynamic, that's +why advanced features like apache configstream are not used. Actually +auth/authz information is build against each request, to make You able +to manipulate access control information, without server restarting +(even graceful). Actually making graceful, is no problem - the point is, +that if You edit Your LDAP with some external tool, +e.g. excellent phpldapadmin, You may not want this tool to execute or force +(in any way) any kind of daemons restart. Another solution, is to put +graceful into cron somewhere, however I guess dynamic access control +is more ee.., well, its better solution :) + +IMPORTANT NOTE 3: +If Your changes in LDAP seems to not working, check some cacheTTL and +other directives with apache ldap_module, You've read this module manual, +didn't You? :) + + +TIPS and HINTS: +Enjoying LDAP power - You can have multiple values for some attributes. +actually no matters how many values You set for apacheLocationOptionsDn +(must be at least one), because search is made with uri and serverName. + +However, You can set more than one serverName with location object, +if You want the have the same URI blocked on more than one webserver, +eg. if Your vhosts has standard location "/statistics", You can +block them for all vhosts you want, no matter, whether real statistics +dir exists in filesystem, or not (auth/authz is made before returning data). +Anyway defining the same location for different vhosts as separated object +should work, however they should have different naming attribute. +If You set two objects, for the same uri and different naming attribute, and +the same vhost servername value, probably the first one found will be used, +I didn't check. +extConfigObject may also apply to more than one URI - the same. +You can also have the same user, valid for more than one vhost, exactly +the same rules apply like above. +One user can have more than one password. + +Actually defining separate objects, makes sens only if +You want to be able to quickly enable/disable particular URI +(or user, or config, etc. etc.), instead of removing it, probably +based on some attribute value defined elsewhere, and applied to ldap filter +in mod-ldap-vhost configuration. + +DEVELOPER's NOTE: +The main trick is, that ap_requires is used to SET requirelines using generated +apr_array_header_t, based on some information source, before it's later used +in normal authz procedure, at appropriate authorization hook. + +TODOs (unsorted): +* general code review (use of per-directory-config ?) +* implement php_admin_flag and php_admin_value setting for vhosts with ldap +* implement logging-related directives for ldap-based vhosts +* implement require group +* implement use of other authentication methods than basic, including X509, +and authentication based not only with apacheExtUserObject, but also with +classic posixAccount/Group, probably with use of other excellent modules +like mod_authz_ldap and others.. +* testing with apache 2.2.x + +* testers are welcomed, probably some nullpointer and overflows possibility +extists, anyway Apache The Greate works holds the line - I tested some +generated module segfaults, and they doesn't break apache itself, module only. \ No newline at end of file