Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/freeradius/mod_auth_radius

The FreeRADIUS Apache module for RADIUS authentication
https://github.com/freeradius/mod_auth_radius

apache client radius

Last synced: about 1 month ago
JSON representation

The FreeRADIUS Apache module for RADIUS authentication

Awesome Lists containing this project

README 

        
mod_auth_radius

===============



0. Branch state

---------------



image:https://travis-ci.org/FreeRADIUS/mod_auth_radius.svg?branch=master["Build Status", link="https://travis-ci.org/FreeRADIUS/mod_auth_radius"]



1. Introduction

---------------



Everyone wants strong authentication over the web.  For us, this means

RADIUS.



Using static passwords & RADIUS authentication over HTTP is a BAD

IDEA.  Everyone can sniff the passwords, as they're sent over the net

in the clear.  We suggest using HTTPS.  RADIUS web authentication is a

REALLY BAD IDEA if you use the same RADIUS server for web and NAS

(dial-up) or firewall users.  Then ANYONE can pretend to be you, and

break through your firewall with minimal effort.



PLEASE use a different RADIUS server for web authentication and

dial-up or firewall users!  If you must use the same server, go for

one-time passwords.  They're ever so much more secure.



Also, do NOT have your RADIUS server visible to the external world.

Doing so makes all kinds of attacks possible.



2. Configuration

----------------



See the example 'httpd.conf' in this directory for a detailed example

of the configuration directives.



You must have at least one authentication method as authoritative.  If

they all return "DECLINED", you get a "server configuration error"

message.



AddRadiusAuth configures the RADIUS server name (and optional port).

You must also specify the shared secret, and tell the RADIUS server

that the web host machine is a valid RADIUS client.  The optional

 field specifies how long Apache waits before giving up, and

deciding that the RADIUS server is down.  It then returns a "DENIED"

error.



If you want, you can specify how long the returned cookies are valid.

The time is in minutes, with the magic value of '0' meaning forever.



The per-dir configuration Cookie Valid time does NOT over-ride the

server configuration.  mod_auth_radius choose the most restrictive of

the two to use.  This way, a site administrator can say all cookies

are valid forever, and then make some directories a bit more secure,

by forcing re-authentication every hour.



If you want logging, use the standard Apache access log.  A log

message is generated ONLY when a user has authenticated, and their

name & file accessed is put in the log file.



The per-dir AddRadiusCallingStationID configuration option will

force the calling station ID string (only static strings) and

include it in authentication requests, if used. If not used, the

default behavior, using the client's remote IP address will be

applied.



3. How it works

---------------



The browser requests a page: http://www.example.com/index.html



Apache notes that the directory is access controlled, and sends a

"Authorization Required".



The browser asks for a username & password, which it then sends to

Apache, along with a request for the page again.



Apache calls mod_auth_radius, which notes that there is no RADIUS

cookie in the request.



mod_auth_radius packages up the username/password into a RADIUS

request, and sends it to the RADIUS server.



The RADIUS server does its magic, and decides yes/no for

authentication.



If no, mod_auth_radius returns DENIED.



If yes, mod_auth_radius returns a cookie containing MD5'd

public+private information.



The web browser uses this cookie on all subsequent requests, and

mod_auth_radius verifies the cookie is valid, and doesn't contact the

RADIUS server again.



4. Some warnings

----------------



This works fine for static passwords (i.e. "user", "password"), but

needs a bit more attention for one-time passwords.  All of the

browsers I've tested don't use the cookie immediately if you're

accessing a directory as:



http://www.example.com/



What's hidden here is that the following files are checked for:



- http://www.example.com/

- http://www.example.com/home.html

- http://www.example.com/home.cgi

- http://www.example.com/index.cgi

- http://www.example.com/index.html



etc., all in sequence.  This module does a 'stat', and returns "NOT

FOUND" when anyone tries to access a file which doesn't exist.

However, it WILL authenticate for a file which does exists, but the

browser may not use the returned cookie when accessing a different

page.



The way to fix this is to point the browser at a specific page. i.e.



http://www.example.com/



Which points to the page 'index.html' (or similar).  That file

should contain text which says "connect to our _secure_ site", where

_secure_ is a link to a specific *page*, not a *directory*.  e.g.



http://www.example.com/secure/index.html



If you do not add in 'index.html' in the link, it won't work

properly.



This method ensures that users are only authenticated once for the

secure pages, and not multiple times.



People using static passwords don't need to do this, but if they

don't, they'll notice that their RADIUS server is getting 1-4 hits for

every web authentication request.



Some browsers (I.E.) have a problem with sending cookies on initial

requests. If you have a file index.html which includes img/foo.gif in

the same directory.  The user authenticates, reads index.html (with

the cookie in the request header), BUT on reading the gifs, the cookie

is NOT included.



This problem can be avoided by EITHER putting the gifs in the same

directory as the index.html file, or putting moving the entire tree

down a node, and having a NEW index.html which points to

./moved/index.html This is ridiculously ugly, but it seems to work.



5. About the cookies

--------------------



The cookies are valid for a specified time, or until the browser

dies.  mod_auth_radius will forcibly try to expire cookies that it

thinks are too old.  If your browser doesn't expire the cookie, you'll

see an authorization required message over and over.  You must then

exit the browser, and re-load the web page.



6. Challenge-Response support

-----------------------------



This module also supports the full RADIUS challenge-response

mechanism.  From the user's perspective, on authenticatation, type in

username & garbage (or NUL) password.  Click , and you'll get an

authentication failure.  This is fine, as mod_auth_radius has secretly

set a cookie, and modified the Basic-Authentication-Realm.



When the authentication fails, click  to continue, and you'll

get another username/password authentication window.  This time,

however, you'll see your username displayed, along with the RADIUS

Reply-Message at the top of the authentication window.  This message

usually includes a challenge.



Type in your username, and put the response to the challenge in the

password field.  Click  again, and you should be authenticated.



The secret is that cookies are being magically set back and forth,

and these cookies include the RADIUS state variable.



The challenge-response works on Netscape 3.x and 4.x, HotJava, but

NOT on Internet Explorer.  I.E. does not appear to follow the relevant

RFCs properly.



7. Other

--------



Any questions or comments can be sent to the FreeRADIUS users list

http://freeradius.org/list/index.html. 



Author:  Alan DeKok