summaryrefslogtreecommitdiff
path: root/www/ap-auth-external/INSTALL
blob: a31036b950106ce7cfd771651a1d2f5288ea66b1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
How to install mod_auth_external.c into the Apache source tree.

NOTES:

 * If you want to use the HARDCODE function option follow the instructions
   in the INSTALL.HARDCODE file in this directory before following these
   instructions.

 * These instructions are for Apache version 1.3.  I don't know if this version
   of mod_auth_external is still compatible with older versions of Apache.

 * There are two ways of installing mod_auth_external. 

     (1) You can statically link it with Apache.  This requires rebuilding
         Apache in such a way that mod_auth_external will be compiled in. 

     (2) You can make mod_auth_external a dynamically loaded module.  If
         your Apache has been built to support dynamically loaded modules
	 you can do this without rebuilding Apache, so it is pretty easy.
	 Performance may be slightly worse with this option.  For information
	 on dynamically loaded modules see http://www.apache.org/docs/dso.html

   Instructions for both options are given here.

 * If you are statically linking mod_auth_external into Apache, you must
   rebuild Apache.  There are two methods of building Apache, the APACI
   method and the manual method.  Instructions for both are given here.  The
   configuration part is the same either way.

 * There is also documentation in the README file, in the AUTHENTICATORS file
   and at the front of the mod_auth_external.c source file.  If you find this
   document unclear, reading those may help.


INSTALL METHOD A: Dynamically Linking Mod_auth_external using apxs:
-------------------------------------------------------------------

Step 1:
	Ensure that your Apache server is configured to handle dynamically
	loaded modules.  Redhat Linux 6.1 does.  To check this, run Apache
	server with the -l command flag, like

	       httpd -l

	If mod_so.c is one of the compiled-in modules, then you are ready
	to go.

Step 2:
	Compile the module using the following command in the mod_auth_external
	distribution directory:

	        apxs -c mod_auth_external.c

	'Apxs' is the Apache extension tool.  It is part of the standard
	Apache installation.  If you don't have it, then your Apache server
	is probably not set up for handling dynamically loaded modules.
	This should create a file named 'mod_auth_external.so'.

	AIX Note:  I'm told that on AIX the 'apxs' command above compiles
	   mod_auth_external.c into mod_auth_external.o correctly, but
	   generation of the shared library file fails with a message like
	   "No csects or exported symbols have been saved."  If this happens,
	   create a file in the current directory named mod_auth_external.exp
	   which contains the two lines below:

	         #! mod_auth_external.o
	         external_auth_module 

           Then run 
	    
		apxs -c mod_auth_external.c -bE:mod_auth_external.exp
 
Step 3:
	Install the module.  Apxs can do this for you too.  Do the following
	command (as root so you can write to Apache's directories and config
	files):

	       apxs -i -a mod_auth_external.so

	This will copy mod_auth_external.so into the proper place, and add
	appropriate AddModule and LoadModule commands to the configuration
	files.  (Actually, it may get the LoadModule command wrong.  See
	below.)

Step 4:
	Go to the CONFIGURATION instructions below.


INSTALL METHOD B: Statically Linking by building Apache with APACI:
-------------------------------------------------------------------

Step 1:
        Read the instructions on how to configure the Apache server in the
        INSTALL file provided with the Apache source.

Step 2:
        When you run the ./configure script, include an --add-module flag,
        giving the full pathname to the mod_auth_external.c file in this
        distribution.  For example, if you have unpacked this distribution
        in /usr/local/src/mod_auth_external and are building Apache for
        installation in /usr/local/apache, you might do:

        ./configure --prefix=/usr/local/apache \
              --add-module=/usr/local/src/mod_auth_external/mod_auth_external.c

        This will copy the mod_auth_external.c file into the correct place in
        the Apache source tree and set things up to link it in.

Step 3:
	Type "make" to compile Apache and "make install" to install it.

Step 4:
	Go to the CONFIGURATION instructions below.


INSTALL METHOD C:  Statically Linking by manually building Apache:
------------------------------------------------------------------

Step 1:
	Read the instructions on how to configure the Apache server in the
	src/INSTALL file provided with the Apache source.

Step 2:
	Copy the mod_auth_external.c file from this distribution into the
	src/modules/extra subdirectory of the Apache source tree.

Step 3:
	Add the following line to the Apache 'Configuration' file:

	   AddModule modules/extra/mod_auth_external.c 

Step 4:
	Run "./Configure" and "make" and "make install" in the src directory
	to configure, compile and install Apache.

Step 4:
	Go to the CONFIGURATION instructions below.

CONFIGURATION:
--------------

There are two parts to doing the configuration.  First you define the
external program and communication method to use in your httpd.conf file,
identifying them with a keyword.  Then you set up specific directories to
use that authenticator, referencing it by keyword.

Step 1:
	If you are using dynamic loading, you'll need to make sure that
	there is a proper "LoadModule" command in the httpd.conf file.
	This should have been put there by 'apxs' but, at least under
	RedHat 6.1, it gets it wrong.  Basically, the 'LoadModule' command
	should look a lot like all the other LoadModule commands.  Something
	like

	    LoadModule external_auth_module modules/mod_auth_external.so

        where the second part is the path from Apache's root directory
	to the location where the module is stored.

	Make sure that apxs didn't put this directive inside any inappropriate
	<IfDefine> directives.  Under RedHat 7.1 it likes to put it inside
	<IfDefine HAVE_PYTHON> which makes no sense.

	Also, if you previously had mod_auth_external installed and are
	installing a new version, apxs may have put a second LoadModule
	command into httpd.conf.  You only need one.  Get rid of the extra.

Step 2:
	Check you httpd.conf file to see if there is a "ClearModuleList"
	command.  If this exists, then you need to add a command like:

	    AddModule mod_auth_external.c

	somewhere below "ClearModuleList" command (probably somewhere among
	the dozens of other AddModule commands).  If you used 'apxs' to
	install mod_auth_external, then this should already be done, but
	it may again be stashed in an inappropriate <IfDefine>.

	The standard Apache configuration files don't have a "ClearModuleList"
	command and don't need an "AddModule" command.  However the standard
	RedHat configuration files do.

Step 3:
	Add the following line(s) to your server's httpd.conf.
	
	If you are using virtual hosts, put them at the end of the
	appropriate <VirtualHost> block.  The declarations must be *inside*
	the <VirtualHost> block to work for a virtual host.  They are not
	inherited from the primary host to the virtual hosts.  Note that most
	Apache SSL servers are set up as virtual hosts, so you'll probably
	need to put these definitions in the <VirtualHost> block for use with
	an SSL server.
	
	Otherwise, just put them anywhere (just before the Virtual Hosts
	section of the config file might make the most sense).

	For external authentication programs:
            AddExternalAuth <keyword> <path-to-authenticator>         
            SetExternalAuthMethod <keyword> <method>

	For HARDCODE functions:
	    AddExternalAuth <keyword> <type>:<path where config file is>
            SetExternalAuthMethod <keyword> function

	<keyword> is some name you choose.  You can configure multiple
	different external authenticators by using different keywords for
	them.

	<path-to-authenticator> is normally the full path where you installed
	your external authentication program.  If you put it in quotes, you
	can include command-line arguments, but these arguments won't be
	processed by a shell, so you can't use wildcards or I/O redirects
	or anything like that.  If you need shell processing of arguments,
	write an sh-script wrapper for your authenticator, and put the path
	to that here.

	<method> defines how the login and password are passed to the
	external authenticator:
          environment    get args from environment variables. (default)
          pipe           read newline-terminated strings from stdin.
	  checkpassword  read null-terminated strings from file descriptor 3.
          function       internal authenticator called as function.
        Environment is the default for historical reasons, but it may be
        insecure on some versions of Unix.  See the README file.

	Examples:

	  ** For external authentication programs using environment variables:

	     AddExternalAuth archive_auth /usr/local/bin/authcheck
	     SetExternalAuthMethod archive_auth environment

	  ** For external authentication programs using a pipe:

	     AddExternalAuth archive_auth /usr/local/bin/authcheck
	     SetExternalAuthMethod archive_auth pipe

	  ** For external authenticators using the checkpassword protocol:

	     AddExternalAuth archive_auth "/bin/checkpassword /bin/true"
	     SetExternalAuthMethod archive_auth checkpassword

   	   ** For HARDCODE functions with no configuration file:

	      AddExternalAuth archive_auth RADIUS:
	      SetExternalAuthMethod archive_auth function

	   ** For HARDCODE functions with a configuration file:

	      AddExternalAuth archive_auth RADIUS:/usr/local/raddb
	      SetExternalAuthMethod archive_auth function
	   
Step 4:
	If you want to use an external program to do group checking, add the 
	following to your server's httpd.conf.

        AddExternalGroup <keyword> <path-to-authenticator>         

        SetExternalGroupMethod <keyword> <method>

	<keyword> is some name you choose to identify this particular
	group checking method.  The keywords for login authenticators and
	group authenticators are separate name spaces, so it doesn't matter
	if these keywords match any you defined in step 1.

	<method> defines how the login and group names are passed to the
	external authenticator:
           environment - authenticator gets data from environment variables.
           pipe - authenticator reads data from standard input.
        Environment is the default.

	Examples:

	  ** For external group check programs using environment variables:

	     AddExternalGroup archive_group /usr/local/bin/groupcheck
	     SetExternalGroupMethod archive_group environment

	  ** For external authentication programs using a pipe:

	     AddExternalGroup archive_group /usr/local/bin/authcheck
	     SetExternalGroupMethod archive_group pipe

Step 5:
	For any directory you want to protect, you need either a
	.htaccess file in the directory or a <Directory> block for the
	directory in your httpd.conf file.

	Note that for .htaccess files to work, you must specify "AllowOverride
	AuthConfig" in the httpd.conf file for any directories they appear
	under.  As distributed, Apache sets "AllowOverride None" for most
	directories.  If this is not changed, .htaccess files will be ignored.

        For normal user authentication, the following directives should be in
        the .htaccess file or <Directory> block:

	   AuthType Basic
	   AuthName <authname>
	   AuthExternal <keyword>
	   require valid-user

       Here <authname> identifies what we are authenticating for - it usually
       appears in the browser's pop-up login windown.  <keyword> matches a
       keyword you defined with AddExternalAuth in step 1.

       If you only want some users to have access to the directory, as opposed
       to all valid users, you can list the users on the "require" line,
       changing it to:

           require user <username1> <username2> ...

       If you want to use the external group check program to allow only
       users in a given group to have access, you could do:

	   AuthType Basic
	   AuthName <name you call this type of authentication>
	   AuthExternal <keyword>
	   GroupExternal <groupkeyword>
           require group <groupname1> <groupname2> ...

       Here <groupkeyword> matches a name you defined with with the 
       AddExternalGroup command in step 2.

       Mod_auth_external is "authoritative" by default.  This means that
       if a login/password are not found to be valid by mod_auth_external,
       then no other authentication methods will be tried, even if you have
       configured them.  If you want login/password pairs that failed
       authentication to be passed only to other authenticators, then you
       should add the directive:

          AuthExternalAuthoritative off

       Of course, if you haven't configured multiple authenticators for the
       directory, then you can ignore this.

       See the Apache manual pages on AuthType, AuthName, require, and
       AuthGroupFile for more information.

Step 6:
	Install your external authentication program in the location named
	by the pathname on your AddExternalAuth directive.

Step 7:
	Restart Apache, so that all the new configuration commands will be
	loaded.  If you have the apachectl command do:

		apachectl restart

        For Redhat 6.1 which doesn't have apachectl, instead do:

		/etc/rc.d/init.d/httpd restart

Step 8:
	Test your changes/code by trying to view a protected page.
	
	If it doesn't work, check the apache error logs.  Some common
	problems:

	  - Miscellaneous odd behaviors.

	    Did you restart the httpd after the last time you editted the
	    httpd.conf file or recompiled the program?

	  - Apache complains about not recognizing "AddExternalAuth" and
	    other mod_auth_external commands.

	    Either the module didn't get installed (are you running the
	    newly compiled copy of httpd?), or it isn't enabled (you
	    may need the AddModule or LoadModule commands described above).

          - It displays pages in a protected directory without asking for
	    a login and password.

	    If you are using .htaccess files, does your httpd.conf file
	    say "AllowOverride AuthConfig" for the directory?  Apache is
	    distributed with "AllowOverride None" set on the cgi-bin
	    directory, which will cause .htaccess files to be ignored.

	  - Error log says "Failed (-1)".
	  
	    Probably means that the module couldn't run the authenticator.
	    Is the path correct?  Is it permitted correctly?  Are the
	    directories it is in permitted correctly?
	    
	  - Error log says "Failed" with some other number after it.
	  
	    The authenticator ran, and exited with the given non-zero return
	    code.  The authenticator program seems not to be working.