From f0f02f06ce7239b1a56c24a43c863fb7f11b031a Mon Sep 17 00:00:00 2001 From: Piotr Wadas Date: Thu, 20 Jul 2006 07:37:04 +0000 Subject: [PATCH] git-svn-id: svn://svn.debian.org/svn/modvhostldap/branches/ext-config/mod-vhost-ldap@57 4dd36cbf-e3fd-0310-983d-db0e06859cf4 --- ...ME.apacheExtConfigRequireValidUser-details | 278 ++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 debian/README.apacheExtConfigRequireValidUser-details diff --git a/debian/README.apacheExtConfigRequireValidUser-details b/debian/README.apacheExtConfigRequireValidUser-details new file mode 100644 index 0000000..361ef3d --- /dev/null +++ b/debian/README.apacheExtConfigRequireValidUser-details @@ -0,0 +1,278 @@ +##################################################################### +##################################################################### +##################################################################### +######## mod_vhost_ldap version 2.0.3 or later ###################### +##################################################################### + + This file contains further considerations and usage examples +of single-value access control entry attribute named +"apacheExtConfigRequireValidUser". Handling of user "validity" is +quite complicated and a little bit different than you could expect, +so even I make sometimes misunderstanding if its current implemen- +tation if this feature. + +I'm going to explain here, how user validity is related to +TWO types of resources, to which access control may be defined: + +I. Location access control (sometimes referred as uri access control, +or virtual host access control) +II. Directory access control (sometimes referred as physical location +access control, or virtualhost-independent access control). + +Resource, depending on case, may mean "location" or "directory", +or "both/no matter which kind of goods" :-). + +"Access control" usually means authentication + authorization (for +polish readers - "uwierzytelnianie" and "autoryzacja"). + +Authentication concerns about various ways of checking validity +of username/password pair. It includes checking whether user +exists in user-information source, and whether supplied password +is valid for supplied user. There are hundreds of methods to +perform such tasks and apache supports many of them. However, +mod_vhost_ldap currently support ONLY "basic" authentication, +which conforms to checking whether user exists and whether applied +password is correct for applied username. Some authentication +methods may be used for authentication and authorization, some +of them cannot (in some situation some information e.g. "realm" +provided by clients with authentication are used to authorize +them, sometimes not), however with modvhostldap authentication +and authorization are two different things. + +Authorization concerns about checking whether particular user is +authorized to connect/use particular resource or particular +kind of resource.Depending on authorization configuration, +a resource may be available only to authenticated users, or +for authenticated and not-authenticated users. Here we +take care only about resources which are available only for +authenticated users, so every not-authenticated user is not +authorized to access particular resources. We don't discuss +resources that don't need users to be authenticated to determine +whether they're authorized or not, and vice versa - we assume, +that every resource which has authentication defined, has +user authorization status determined in some way, which will +be explained below. + +Authentication is most simple of all of this - authenticated +user is a user which provided username and password, and +the pair was verified in some way. Http authentication status +information is then kept in http headers (usually until +browser or browser-window is not reopened, depending on browser. + +First we define what's actually defined by access control entry, +and what is NOT defined by access control entry. + +In both cases, (location and directory) access control entry +defines whether particular resource is protected, however +with directory, existing access entry means that directory +has access control, and for location, existing access entry +means,that location is protected if and only if virtual host +has access control enabled. you can enable/disable location access +control for virtualhost, no matter whether access control +entry for this location exists - on virtual host configuration +level, by setting apacheExtConfigHasRequireLine attribute to +TRUE or FALSE. if this attribute for vhost is FALSE, location +access control won't be checked at all. +Directory access control is always checked, no matter, whether +virtualhost has access control enabled, or not. LAC is configured +against particular address on (with) particular virtual server, DAC +is configured against physical location of the resource, no matter +whether it is accessed by some alias address, or some uri +directly available under virtual server directory tree. (www.internal.com/ and below). +Sometimes you may want particular file or directory +on the disk to be protected, no matter which way user tries +to access it, and sometimes you may want that some particular +URL to be protected, if its accessed via www.domain.com, but +opened e.g. from internal network (when it's accessed via www.inernal.com +virtualhost, which is available for internally-conected clients. + +Directory access control has higher level of importance than +location access control. Secured directory is secured no matter +under which location it's accessed. If you secure directory +as directory, and you secure location, location authentication +and authorization will be checked first, and if allowed, directory +authentication and authorization will be checked, and if +denied - user will be denied access. Authentication information +are stored somewhere in http headers, so once authenticated +user data will be passed to directory authentication. +if the same user is authorized to access directory, access +will be granted, if perlocation-authenticated user is not +authorized to access directory, a prompt for another +authentication data will be displayed. This may cause +to annoying results, as authentication information in http +headers would be probably replaced (?), and new values won't +match location requirements. However i'm not sure how this +works, I didn't tested it, it's possible that headers may contain +information for location and directory, anyway it's recommended to +avoiding such situation, to always have clearance which set of access +control settings are applied to the resource client wants access. +In doubt I suggest you to configure per-directory access control, +in almost all cases this is what you want. + +Now, for apache there are three ways in which user can be +authorized for resource: user may be valid-user, user may +be one of exactly defined authorized users, or user may +be member of authorized group. for details refer to apache documentation +of "Require" directives, anyway, modvhostldap currently +supports valid-user and userlist, and this is difference, +which is determined by apacheExtConfigRequireValidUser attribute. + +Location "Require" directive is created for +each request for each vhost which have has LAC enabled +(hasRequireLines = TRUE), and for which there's found +access control object, which has the same or higher +uri as its apacheExtConfigUri value. + +Directory Require directive is created +if there's found access control object, which has +the same or higher directory as its apacheExtConfigPath value. + +Let's assume that if we're processing per-location config +then servername of the http request is "internal", and uri of the +request is "/abcd/xyz/protected/" (so we have +http://internal/abcd/protected/xyz/" +First is checked whether "internal" HasRequireLines is TRUE. +If yes, then there's made a lookup for access control +entry, which has apacheExtConfigServerName value = internal +and apacheExtConfigUri value set to a value, +which is contained in '/abcd/protected/xyz' starting +from left. so access control objects which have +apacheExtConfigUri like: "/", "/abc", +"/abcd/xyz/protected" and "/abcd/xyz/protected/" +will match. Finally, if the full string is reached, +and access control object is not found, error is +reported - (access control configured but no +access control objects found), and access control +is not applied. + +And - other case - if we're processing per-directory config, +then match is made exactly the same way, except that +servername is not checked. If higher (shorter) or equal +directory value has acl object with this value - object +is matched. If full string is reached and object is not found, +access control is not applied, and no error is reported. + +Now ACL object, if found, is examined. +If apacheExtConfigRequireValidUser attribute for it +has value set to "TRUE", then +configuration is processed as "Require valid-user" +(access shoud be granted to any valid user). +analog directive, +If it's "FALSE", then configuration +is processed as "Require user ..." directive, userlist +is created, and access is granted to any valid user, +which username is on the list. +List, if needed, is created depending on values +of attribute apacheExtConfigUserDn which must in this +case contain full distinguished names of the users, +which should have access granted. Username "nobody" +is always appended first, before appending attribute +values (loginnames), to avoid situation, when +apacheExtConfigRequireValidUser = FALSE, and no apacheExtConfigUserDn +values exist in entry ("Require user" if defined, must contain at least one username). + +So access gets configured, and then it comes to authentication. +Further processing depends whether it's case I or II. +In case I - valid user, is user which matches the following filter: +(& + (_D_) + (objectClass=apacheExtendedConfigUserObject) + (apacheExtConfigUserServerName=_A_) + (apacheExtConfigUserLocationUri=_G_) +) + +and in case II +(& + (_D_) + (objectClass=apacheExtendedConfigUserObject) + (apacheExtConfigUserDirectoryName=_E_) +) + +where _D_ is global user-defined filter, and other attributes +have values the same as access control object. +More details about used filters and global +user-defined filter you'll find in vhost_ldap.conf + +Finally, in both cases, if access control object +has apacheExtConfigRequireValidUser = FALSE, user is authenticated, +loginname is found on the list, access is granted, or +of the apacheExtConfigRequireValidUser = TRUE,and user is authenticated, +access is granted, otherwise access is denied. +This final stage, in comparison to analog configuration files, +is the same as checking context in which particular user has been +defined - or . +Simply - with .htaccess context is determined based on +the location of the .htaccess file, in common configuration +context is determined by the context :-), and with ldap +context is determined by attributes of the particular webuser. +In general- it means, that valid-user is not only a user which +has authenticated successfully, but also is valid for +specified resource. Directive "Require user nobody [...]" +allows you to limit all users valid for a resource to exactly +defined list. + +For each user object, supplied password is checked against +as clear text, htpasswd format, or unix crypt format, and with +debug all of them are logged, and additionaly. information +which one matched (or none) is logged too. + +So, to be short at last - access control has particular precendence, +there are some differences between location and directory access +processing. You always need to specify inside userobject +for which resource it is valid, and, additionaly, if you set +apacheExtConfigRequireValidUser=FALSE, then you need to +put webuser object DN into apacheExtConfigUserDn attribute +of the access entry related to this resource. Applied +password is checked against mostly used formats. +And, you can have multiple locations, directories and servernames +for access config entries, and user entries, and (ugh), +you can have multiple access control entries for virtualhost(s). + +If you get into mess, and things doesn't work, you can disable +some part(s) of authentication process. any trouble with +authentication won't impact rest of virtualhost filesystem. +Aliased directiories are substituted first, so directory +access control entries will apply only to final real-directory +or file name. + +Aliasing match works similar way as Directory and Location +match - there's a try to find object which define targed physical +location for current URI, and this target (existing or not), +has precedence over (existing or not) URL part(s). +And you can have multiple aliases for virtualhost, and +multiple virtual URI's for one target. + +If you create entries, which coincidents, like two +alias object which specify the same url and vhost, but +different targets, or two uses with the same +logins and the same permissions but e.g. different passwords, +only first found will be used (each matching is done only once), +and it's hard to predict which one this would actually be. +Creating users without passwords at all, is avoided by +schema. + +Note, that all this stuff is of course checked before actual +resource is returned to browser, so any of alias targets, or +users defined as valid, doesn't need to be existing - if +they don't exist, finally some HTTP error will be returned, but +existence of objects doesn't affect processing itself. + +And one note about user-defined filter - it's appended +checked as normal standalone ldap filter, and +appended to all searches, so it may be considered "global". +There's plan to implement directives to support user-defined +filters to be applied to specified elements of configuration, +however I'm not sure whether this makes sense. Usage +of such filter is usually related to enabling/disabling +objects. E.g. if you have some coustome attribute of the objects +like "isActive" or "toRemove" or something, and you set it +to TRUE or FALSE, you may then apply it to user-defined +filter, to include only objects, which have this attribute +set to "FALSE" or doesn't have it set at all, e.g. + + ( | (isActive=TRUE)(!(isActive=*)) ) + +(isActive equal TRUE, or isActive not equal to anything). + +Have fun, feedback welcomed :) +Piotr Wadas \ No newline at end of file -- 2.45.1