]>
Commit | Line | Data |
---|---|---|
f0f02f06 PW |
1 | ##################################################################### |
2 | ##################################################################### | |
3 | ##################################################################### | |
4 | ######## mod_vhost_ldap version 2.0.3 or later ###################### | |
5 | ##################################################################### | |
6 | ||
7 | This file contains further considerations and usage examples | |
8 | of single-value access control entry attribute named | |
9 | "apacheExtConfigRequireValidUser". Handling of user "validity" is | |
10 | quite complicated and a little bit different than you could expect, | |
11 | so even I make sometimes misunderstanding if its current implemen- | |
12 | tation if this feature. | |
13 | ||
14 | I'm going to explain here, how user validity is related to | |
15 | TWO types of resources, to which access control may be defined: | |
16 | ||
17 | I. Location access control (sometimes referred as uri access control, | |
18 | or virtual host access control) | |
19 | II. Directory access control (sometimes referred as physical location | |
20 | access control, or virtualhost-independent access control). | |
21 | ||
22 | Resource, depending on case, may mean "location" or "directory", | |
23 | or "both/no matter which kind of goods" :-). | |
24 | ||
25 | "Access control" usually means authentication + authorization (for | |
26 | polish readers - "uwierzytelnianie" and "autoryzacja"). | |
27 | ||
28 | Authentication concerns about various ways of checking validity | |
29 | of username/password pair. It includes checking whether user | |
30 | exists in user-information source, and whether supplied password | |
31 | is valid for supplied user. There are hundreds of methods to | |
32 | perform such tasks and apache supports many of them. However, | |
33 | mod_vhost_ldap currently support ONLY "basic" authentication, | |
34 | which conforms to checking whether user exists and whether applied | |
35 | password is correct for applied username. Some authentication | |
36 | methods may be used for authentication and authorization, some | |
37 | of them cannot (in some situation some information e.g. "realm" | |
38 | provided by clients with authentication are used to authorize | |
39 | them, sometimes not), however with modvhostldap authentication | |
40 | and authorization are two different things. | |
41 | ||
42 | Authorization concerns about checking whether particular user is | |
43 | authorized to connect/use particular resource or particular | |
44 | kind of resource.Depending on authorization configuration, | |
45 | a resource may be available only to authenticated users, or | |
46 | for authenticated and not-authenticated users. Here we | |
47 | take care only about resources which are available only for | |
48 | authenticated users, so every not-authenticated user is not | |
49 | authorized to access particular resources. We don't discuss | |
50 | resources that don't need users to be authenticated to determine | |
51 | whether they're authorized or not, and vice versa - we assume, | |
52 | that every resource which has authentication defined, has | |
53 | user authorization status determined in some way, which will | |
54 | be explained below. | |
55 | ||
56 | Authentication is most simple of all of this - authenticated | |
57 | user is a user which provided username and password, and | |
58 | the pair was verified in some way. Http authentication status | |
59 | information is then kept in http headers (usually until | |
60 | browser or browser-window is not reopened, depending on browser. | |
61 | ||
62 | First we define what's actually defined by access control entry, | |
63 | and what is NOT defined by access control entry. | |
64 | ||
65 | In both cases, (location and directory) access control entry | |
66 | defines whether particular resource is protected, however | |
67 | with directory, existing access entry means that directory | |
68 | has access control, and for location, existing access entry | |
69 | means,that location is protected if and only if virtual host | |
70 | has access control enabled. you can enable/disable location access | |
71 | control for virtualhost, no matter whether access control | |
72 | entry for this location exists - on virtual host configuration | |
73 | level, by setting apacheExtConfigHasRequireLine attribute to | |
74 | TRUE or FALSE. if this attribute for vhost is FALSE, location | |
75 | access control won't be checked at all. | |
76 | Directory access control is always checked, no matter, whether | |
77 | virtualhost has access control enabled, or not. LAC is configured | |
78 | against particular address on (with) particular virtual server, DAC | |
79 | is configured against physical location of the resource, no matter | |
80 | whether it is accessed by some alias address, or some uri | |
81 | directly available under virtual server directory tree. (www.internal.com/ and below). | |
82 | Sometimes you may want particular file or directory | |
83 | on the disk to be protected, no matter which way user tries | |
84 | to access it, and sometimes you may want that some particular | |
85 | URL to be protected, if its accessed via www.domain.com, but | |
86 | opened e.g. from internal network (when it's accessed via www.inernal.com | |
87 | virtualhost, which is available for internally-conected clients. | |
88 | ||
89 | Directory access control has higher level of importance than | |
90 | location access control. Secured directory is secured no matter | |
91 | under which location it's accessed. If you secure directory | |
92 | as directory, and you secure location, location authentication | |
93 | and authorization will be checked first, and if allowed, directory | |
94 | authentication and authorization will be checked, and if | |
95 | denied - user will be denied access. Authentication information | |
96 | are stored somewhere in http headers, so once authenticated | |
97 | user data will be passed to directory authentication. | |
98 | if the same user is authorized to access directory, access | |
99 | will be granted, if perlocation-authenticated user is not | |
100 | authorized to access directory, a prompt for another | |
101 | authentication data will be displayed. This may cause | |
102 | to annoying results, as authentication information in http | |
103 | headers would be probably replaced (?), and new values won't | |
104 | match location requirements. However i'm not sure how this | |
105 | works, I didn't tested it, it's possible that headers may contain | |
106 | information for location and directory, anyway it's recommended to | |
107 | avoiding such situation, to always have clearance which set of access | |
108 | control settings are applied to the resource client wants access. | |
109 | In doubt I suggest you to configure per-directory access control, | |
110 | in almost all cases this is what you want. | |
111 | ||
112 | Now, for apache there are three ways in which user can be | |
113 | authorized for resource: user may be valid-user, user may | |
114 | be one of exactly defined authorized users, or user may | |
115 | be member of authorized group. for details refer to apache documentation | |
116 | of "Require" directives, anyway, modvhostldap currently | |
117 | supports valid-user and userlist, and this is difference, | |
118 | which is determined by apacheExtConfigRequireValidUser attribute. | |
119 | ||
120 | Location "Require" directive is created for | |
121 | each request for each vhost which have has LAC enabled | |
122 | (hasRequireLines = TRUE), and for which there's found | |
123 | access control object, which has the same or higher | |
124 | uri as its apacheExtConfigUri value. | |
125 | ||
126 | Directory Require directive is created | |
127 | if there's found access control object, which has | |
128 | the same or higher directory as its apacheExtConfigPath value. | |
129 | ||
130 | Let's assume that if we're processing per-location config | |
131 | then servername of the http request is "internal", and uri of the | |
132 | request is "/abcd/xyz/protected/" (so we have | |
133 | http://internal/abcd/protected/xyz/" | |
134 | First is checked whether "internal" HasRequireLines is TRUE. | |
135 | If yes, then there's made a lookup for access control | |
136 | entry, which has apacheExtConfigServerName value = internal | |
137 | and apacheExtConfigUri value set to a value, | |
138 | which is contained in '/abcd/protected/xyz' starting | |
139 | from left. so access control objects which have | |
140 | apacheExtConfigUri like: "/", "/abc", | |
141 | "/abcd/xyz/protected" and "/abcd/xyz/protected/" | |
142 | will match. Finally, if the full string is reached, | |
143 | and access control object is not found, error is | |
144 | reported - (access control configured but no | |
145 | access control objects found), and access control | |
146 | is not applied. | |
147 | ||
148 | And - other case - if we're processing per-directory config, | |
149 | then match is made exactly the same way, except that | |
150 | servername is not checked. If higher (shorter) or equal | |
151 | directory value has acl object with this value - object | |
152 | is matched. If full string is reached and object is not found, | |
153 | access control is not applied, and no error is reported. | |
154 | ||
155 | Now ACL object, if found, is examined. | |
156 | If apacheExtConfigRequireValidUser attribute for it | |
157 | has value set to "TRUE", then | |
158 | configuration is processed as "Require valid-user" | |
159 | (access shoud be granted to any valid user). | |
160 | analog directive, | |
161 | If it's "FALSE", then configuration | |
162 | is processed as "Require user ..." directive, userlist | |
163 | is created, and access is granted to any valid user, | |
164 | which username is on the list. | |
165 | List, if needed, is created depending on values | |
166 | of attribute apacheExtConfigUserDn which must in this | |
167 | case contain full distinguished names of the users, | |
168 | which should have access granted. Username "nobody" | |
169 | is always appended first, before appending attribute | |
170 | values (loginnames), to avoid situation, when | |
171 | apacheExtConfigRequireValidUser = FALSE, and no apacheExtConfigUserDn | |
172 | values exist in entry ("Require user" if defined, must contain at least one username). | |
173 | ||
174 | So access gets configured, and then it comes to authentication. | |
175 | Further processing depends whether it's case I or II. | |
176 | In case I - valid user, is user which matches the following filter: | |
177 | (& | |
178 | (_D_) | |
179 | (objectClass=apacheExtendedConfigUserObject) | |
180 | (apacheExtConfigUserServerName=_A_) | |
181 | (apacheExtConfigUserLocationUri=_G_) | |
182 | ) | |
183 | ||
184 | and in case II | |
185 | (& | |
186 | (_D_) | |
187 | (objectClass=apacheExtendedConfigUserObject) | |
188 | (apacheExtConfigUserDirectoryName=_E_) | |
189 | ) | |
190 | ||
191 | where _D_ is global user-defined filter, and other attributes | |
192 | have values the same as access control object. | |
193 | More details about used filters and global | |
194 | user-defined filter you'll find in vhost_ldap.conf | |
195 | ||
196 | Finally, in both cases, if access control object | |
197 | has apacheExtConfigRequireValidUser = FALSE, user is authenticated, | |
198 | loginname is found on the list, access is granted, or | |
199 | of the apacheExtConfigRequireValidUser = TRUE,and user is authenticated, | |
200 | access is granted, otherwise access is denied. | |
201 | This final stage, in comparison to analog configuration files, | |
202 | is the same as checking context in which particular user has been | |
203 | defined - <Directory /some/dir> or <Location /abcd/xyz/protected>. | |
204 | Simply - with .htaccess context is determined based on | |
205 | the location of the .htaccess file, in common configuration | |
206 | context is determined by the context :-), and with ldap | |
207 | context is determined by attributes of the particular webuser. | |
208 | In general- it means, that valid-user is not only a user which | |
209 | has authenticated successfully, but also is valid for | |
210 | specified resource. Directive "Require user nobody [...]" | |
211 | allows you to limit all users valid for a resource to exactly | |
212 | defined list. | |
213 | ||
214 | For each user object, supplied password is checked against | |
215 | as clear text, htpasswd format, or unix crypt format, and with | |
216 | debug all of them are logged, and additionaly. information | |
217 | which one matched (or none) is logged too. | |
218 | ||
219 | So, to be short at last - access control has particular precendence, | |
220 | there are some differences between location and directory access | |
221 | processing. You always need to specify inside userobject | |
222 | for which resource it is valid, and, additionaly, if you set | |
223 | apacheExtConfigRequireValidUser=FALSE, then you need to | |
224 | put webuser object DN into apacheExtConfigUserDn attribute | |
225 | of the access entry related to this resource. Applied | |
226 | password is checked against mostly used formats. | |
227 | And, you can have multiple locations, directories and servernames | |
228 | for access config entries, and user entries, and (ugh), | |
229 | you can have multiple access control entries for virtualhost(s). | |
230 | ||
231 | If you get into mess, and things doesn't work, you can disable | |
232 | some part(s) of authentication process. any trouble with | |
233 | authentication won't impact rest of virtualhost filesystem. | |
234 | Aliased directiories are substituted first, so directory | |
235 | access control entries will apply only to final real-directory | |
236 | or file name. | |
237 | ||
238 | Aliasing match works similar way as Directory and Location | |
239 | match - there's a try to find object which define targed physical | |
240 | location for current URI, and this target (existing or not), | |
241 | has precedence over (existing or not) URL part(s). | |
242 | And you can have multiple aliases for virtualhost, and | |
243 | multiple virtual URI's for one target. | |
244 | ||
245 | If you create entries, which coincidents, like two | |
246 | alias object which specify the same url and vhost, but | |
247 | different targets, or two uses with the same | |
248 | logins and the same permissions but e.g. different passwords, | |
249 | only first found will be used (each matching is done only once), | |
250 | and it's hard to predict which one this would actually be. | |
251 | Creating users without passwords at all, is avoided by | |
252 | schema. | |
253 | ||
254 | Note, that all this stuff is of course checked before actual | |
255 | resource is returned to browser, so any of alias targets, or | |
256 | users defined as valid, doesn't need to be existing - if | |
257 | they don't exist, finally some HTTP error will be returned, but | |
258 | existence of objects doesn't affect processing itself. | |
259 | ||
260 | And one note about user-defined filter - it's appended | |
261 | checked as normal standalone ldap filter, and | |
262 | appended to all searches, so it may be considered "global". | |
263 | There's plan to implement directives to support user-defined | |
264 | filters to be applied to specified elements of configuration, | |
265 | however I'm not sure whether this makes sense. Usage | |
266 | of such filter is usually related to enabling/disabling | |
267 | objects. E.g. if you have some coustome attribute of the objects | |
268 | like "isActive" or "toRemove" or something, and you set it | |
269 | to TRUE or FALSE, you may then apply it to user-defined | |
270 | filter, to include only objects, which have this attribute | |
271 | set to "FALSE" or doesn't have it set at all, e.g. | |
272 | ||
273 | ( | (isActive=TRUE)(!(isActive=*)) ) | |
274 | ||
275 | (isActive equal TRUE, or isActive not equal to anything). | |
276 | ||
277 | Have fun, feedback welcomed :) | |
278 | Piotr Wadas <pwadas@jewish.org.pl> |