"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Introduction
2 ============
3
4 Everyone wants strong authentication over the web. For us, this means
5 RADIUS.
6
7 Using static passwords & RADIUS authentication over the web is a BAD
8 IDEA. Everyone can sniff the passwords, as they're sent over the net
9 in the clear. RADIUS web authentication is a REALLY BAD IDEA if you
10 use the same RADIUS server for web and NAS (dial-up) or firewall
11 users. Then ANYONE can pretend to be you, and break through your
12 firewall with minimal effort.
13
14 PLEASE use a different RADIUS server for web authentication and
15 dial-up or firewall users! If you must use the same server, go for
16 one-time passwords. They're ever so much more secure.
17
18 Also, do NOT have your RADIUS server visible to the external world.
19 Doing so makes all kinds of attacks possible.
20
21
22 Configuration
23 =============
24
25 See the example 'httpd.conf' in this directory for a detailed example
26 of the configuration directives.
27
28 You must have at least one authentication method as authoritative. If
29 they all return "DECLINED", you get a "server configuration error"
30 message.
31
32 AddRadiusAuth configures the RADIUS server name (and optional port).
33 You must also specify the shared secret, and tell the RADIUS server
34 that the web host machine is a valid RADIUS client. The optional
35 <seconds> field specifies how long Apache waits before giving up, and
36 deciding that the RADIUS server is down. It then returns a "DENIED"
37 error.
38
39 If you want, you can specify how long the returned cookies are valid.
40 The time is in minutes, with the magic value of '0' meaning forever.
41
42
43 The per-dir configuration Cookie Valid time does NOT over-ride the
44 server configuration. mod_auth_radius choose the most restrictive of
45 the two to use. This way, a site administrator can say all cookies
46 are valid forever, and then make some directories a bit more secure,
47 by forcing re-authentication every hour.
48
49 If you want logging, use the standard Apache access log. A log
50 message is generated ONLY when a user has authenticated, and their
51 name & file accessed is put in the log file.
52
53
54 How it works
55 ============
56
57 The browser requests a page: http://www.example.com/index.html
58
59 Apache notes that the directory is access controlled, and sends a
60 "Authorization Required".
61
62 The browser asks for a username & password, which it then sends to
63 Apache, along with a request for the page again.
64
65 Apache calls mod_auth_radius, which notes that there is no RADIUS
66 cookie in the request.
67
68 mod_auth_radius packages up the username/password into a RADIUS
69 request, and sends it to the RADIUS server.
70
71 The RADIUS server does its magic, and decides yes/no for
72 authentication.
73
74 If no, mod_auth_radius returns DENIED.
75
76 If yes, mod_auth_radius returns a cookie containing MD5'd
77 public+private information.
78
79 The web browser uses this cookie on all subsequent requests, and
80 mod_auth_radius verifies the cookie is valid, and doesn't contact the
81 RADIUS server again.
82
83
84 Some warnings
85 =============
86
87 This works fine for static passwords (i.e. "user", "password"), but
88 needs a bit more attention for one-time passwords. All of the
89 browsers I've tested don't use the cookie immediately if you're
90 accessing a directory as:
91
92 http://www.example.com/
93
94 What's hidden here is that the following files are checked for:
95
96 http://www.example.com/
97 http://www.example.com/home.html
98 http://www.example.com/home.cgi
99 http://www.example.com/index.cgi
100 http://www.example.com/index.html
101
102 etc., all in sequence. This module does a 'stat', and returns "NOT
103 FOUND" when anyone tries to access a file which doesn't exist.
104 However, it WILL authenticate for a file which does exists, but the
105 browser may not use the returned cookie when accessing a different
106 page.
107
108 The way to fix this is to point the browser at a specific page. i.e.
109
110 http://www.example.com/
111
112 Which points to the page 'index.html' (or similar). That file
113 should contain text which says "connect to our _secure_ site", where
114 _secure_ is a link to a specific *page*, not a *directory*. e.g.
115
116 http://www.example.com/secure/index.html
117
118 If you do not add in 'index.html' in the link, it won't work
119 properly.
120
121 This method ensures that users are only authenticated once for the
122 secure pages, and not multiple times.
123
124 People using static passwords don't need to do this, but if they
125 don't, they'll notice that their RADIUS server is getting 1-4 hits for
126 every web authentication request.
127
128
129 Some browsers (I.E.) have a problem with sending cookies on initial
130 requests. If you have a file index.html which includes img/foo.gif in
131 the same directory. The user authenticates, reads index.html (with
132 the cookie in the request header), BUT on reading the gifs, the cookie
133 is NOT included.
134
135 This problem can be avoided by EITHER putting the gifs in the same
136 directory as the index.html file, or putting moving the entire tree
137 down a node, and having a NEW index.html which points to
138 ./moved/index.html This is ridiculously ugly, but it seems to work.
139
140
141 About the cookies
142 =================
143
144 The cookies are valid for a specified time, or until the browser
145 dies. mod_auth_radius will forcibly try to expire cookies that it
146 thinks are too old. If your browser doesn't expire the cookie, you'll
147 see an authorization required message over and over. You must then
148 exit the browser, and re-load the web page.
149
150
151 Challenge-Response support
152 ==========================
153
154 This module also supports the full RADIUS challenge-response
155 mechanism. From the user's perspective, on authenticatation, type in
156 username & garbage (or NUL) password. Click <OK>, and you'll get an
157 authentication failure. This is fine, as mod_auth_radius has secretly
158 set a cookie, and modified the Basic-Authentication-Realm.
159
160 When the authentication fails, click <OK> to continue, and you'll
161 get another username/password authentication window. This time,
162 however, you'll see your username displayed, along with the RADIUS
163 Reply-Message at the top of the authentication window. This message
164 usually includes a challenge.
165
166 Type in your username, and put the response to the challenge in the
167 password field. Click <OK> again, and you should be authenticated.
168
169 The secret is that cookies are being magically set back and forth,
170 and these cookies include the RADIUS state variable.
171
172 The challenge-response works on Netscape 3.x and 4.x, HotJava, but
173 NOT on Internet Explorer. I.E. does not appear to follow the relevant
174 RFCs properly.
175
176
177 Other
178 =====
179
180 Any questions or comments can be sent to me at: aland@freeradius.org
181
182 --
183 Author: Alan DeKok <aland@freeradius.org>
184 $Id: README,v 1.5 2003/02/25 16:50:03 aland Exp $