Using External Authentication or Authentication Bypass
Overview
By default, Urchin authentication is performed when the Urchin Session Controller (session.cgi) calls the "auth" binary located in the "bin" directory of the Urchin Installation. This binary queries the configuration database and compares the username and password provided with that stored in the configuration. An exit code signifying either success or failure is returned to the Session Controller. The location of the authentication binary can be controlled with a configuration change. This modular design allows administrators to call an external authentication program instead of the default "auth" binary.
Shown in the above diagram, this external authentication program could perform any desired authentication function including "LDAP" and other database calls. As long as the program is executable by the same user that "urchinwebd" (Urchin's Apache web server) is running as and conforms to the input/output requirements, Urchin can be easily modified to use a different form of authentication.
Specifying the Authentication Routine
To configure which authentication routine the Session Controller calls, edit the "etc/session.conf" file located in the Urchin Installation. This file contains configurable parameters that control the behavior of the Session Controller including which routine to call for authentication. Edit the line:
AUTHENTICATION: ../bin/auth
Replace, the "../bin/auth" with the path to your authentication routine. Be sure that the authentication routine is executable by the same user that "urchinwebd" is running as.
Input/Output Requirements
When the Session Controller calls the authentication routine, it will pass the username, password, and the remote IP address of the user as command line arguments, such that:
argv[1] = username
argv[2] = password
argv[3] = remote_addr
The external authentication routine could choose to ignore any or all of these parameters. But typical authentication routines will at least look at the first two. After performing any or all desired authentication, the routine should exit with a code equal to zero for success and a minus one for failure.
Exit Code
0 = successful authentication
-1 = authentication failed
The above authentication interface allows administrators to easily customize their own routines for validating user logins.
Bypassing Authentication
Using the above techniques, the Urchin authentication can be purposefully bypassed. In the case where a hosting provider wants to use the entire Urchin System for controlling users and groups, but they have already authenticated the user by the time the user arrives at Urchin, bypassing the authentication is an option to avoid a double login. As long as the host can guarantee that access to the Urchin System is controlled from an authenticating portal and that the username cannot be tampered with, the host can bypass authentication using the following technique.
To bypass the authentication create a dummy external authentication routine that always exits with a zero. For example, perl code might look like:
#!/usr/bin/perl
exit(0);
Point the Session Controller at this dummy authentication routine by editing the "etc/session.conf" file to point to this dummy routine as described above. Next, simply provide a link that looks like:
http://hostname:9999/session.cgi?action=login&user=paul
Modify the above link to point to your actual hostname and port, and modify the user to the point to the desired username or variable. The dummy authentication routine will automatically approve this login. Please use this method with care to avoid security problems.
Note for Windows Users
In order to provide similiar functionality in Windows environments where Perl is not installed, a simple noauth.exe binary is available from the Helper Scripts area of the Urchin Support web site. This binary is merely a "no-op" - it simply returns a successful status when called. Be sure you understand the security implications of this before implementing this solution.