====================================== Admin Guide for Mod_auth_xradius ====================================== TABLE OF CONTENTS Overview Configuration - Default Configuration for mod_auth_xradius - Supported mod_auth_xradius directives - Steps to configure mod_auth_xradius Troubleshooting Legal Notices NOTE: Much of the information in this document has been taken from the www.outoforder.cc site: http://www.outoforder.cc/projects/apache/mod_auth_xradius/ ====================================== OVERVIEW -------------------------------------- Mod_auth_xradius is an Apache module which provides add-on feature to the apache to authenticate to all available RADIUS servers. This module enables Apache web server to act as a radius client. The mod_auth_xradius uses basic HTTP authentication to maintain sessions instead of cookies which will help to avoid the problems with page display when the cookies are disabled in the client browser. ====================================== CONFIGURATION -------------------------------------- Default Configuration for mod_auth_xradius -------------------------------------- AuthXRadiusRetries 5 AuthXRadiusTimeout 2 AuthXRadiusAddServer "SERVERNAME.COM" "SECRET" AuthName "RADIUS" AuthBasicProvider xradius AuthType basic AuthBasicAuthoritative off require valid-user Summary of Supported Directives -------------------------------------- AuthXRadiusAddServer:- Description: Add a RADIUS server. Syntax: AuthXRadiusAddServer server_address shared_secret Default: none Context: directory, .htaccess. This directive appends to a list of RADIUS servers to use for Authentication. The server address is of the form hostname[:port]. If no port is supplied, the default of 1812 is used. AuthXRadiusAddServer "10.0.0.10:1783" "secret" # Other Authentication Commands AuthXRadiusCache :- Description: Configure Authentication Caching Syntax: AuthXRadiusCache [dbm|memcache|none] [path|server list|-] Default: none - Context: server config This directive configures the Authentication Cache for mod_auth_xradius. Both positive and negative results from the RADIUS servers are stored in the cache. dbm Uses an APR DBM to cache authentication results. The argument is a relative or absolute path to be used as the DBM Cache file. None Turns off all caching of authentication results. Example Usage: AuthXRadiusCache dbm "10.0.0.1 10.0.0.2 10.0.0.3" AuthXRadiusCacheTimeout:- Description: Configure Authentication Caching Syntax: AuthXRadiusCache seconds Default: 600 Context: server config Sets the Cache Timeout. Example Usage: ## Set the Timeout for 1 hour (3600 Seconds) AuthXRadiusCacheTimeout 3600 AuthXRadiusRejectBlank:- Description: If enabled, Blank passwords will be rejected without querying the RADIUS Servers. Syntax: AuthXRadiusRejectBlank [on|off] Default: off Context: directory, .htaccess. If enabled, any user submitting a blank password will be rejected, without checking with a RADIUS Server or the Authentication Caches. AuthXRadiusTimeout:- Description: Set how long to wait for a reply from a RADIUS server. Syntax: AuthXRadiusTimeout seconds Default: 2 Context: directory, .htaccess. This determines how long mod_auth_xradius will wait for a reply before giving up on a RADIUS Server. AuthXRadiusTimeout 5 # Other Authentication Commands AuthXRadiusRetries:- Description: Set the number of retries per-request. Syntax: AuthXRadiusRetries number Default: 2 Context: directory, .htaccess. This directive sets the number of attempts to send a RADIUS request before giving up. AuthXRadiusRetries 5 # Other Authentication Commands AuthXRadiusTimeout:- Description: Set how long to wait for a reply from a RADIUS server. Syntax: AuthXRadiusTimeout seconds Default: 2 Context: directory, .htaccess. This determines how long mod_auth_xradius will wait for a reply before giving up on a RADIUS Server. AuthXRadiusTimeout 5 # Other Authentication Commands Steps to configure mod_auth_xradius ------------------------------------- Before starting configuring the module, make sure your RADIUS environment is configured (that is, AAA, /etc/opt/aaa/users, /etc/opt/aaa/clients and others.). 1. In order to load the module when Apache starts, add the following line to the httpd.conf file: LoadModule auth_xradius_module modules/mod_auth_xradius.so CONFIGURING AAA RADIUS Following are the steps to configure AAA RADIUS. 1) Install Apache (2.2.8 onwards) with mod_auth_xradius support. 2) Configure the file /etc/opt/aaa/users with the following contents: # Any comments in the file will be removed by Server Manager test_user Password = password Password = 3) Configure the file /etc/opt/aaa/clients # Any comments in the file will be removed by Server Manager localhost secret type=merit+interlink:proxy v1 < Client Name > type=none:nas+proxy v1 4) Start the radius server /opt/aaa/bin/radiusd more info will be found at http://docs.hp.com/en/T1428-90056/ch06s02.html 5)Load the mod_auth_xradius module. To do this, add the LoadModule statement for mod_auth_xradius. LoadModule auth_xradius_module modules/mod_auth_xradius.so 6) The configuration of mod_auth_xradius can be done per directory. The configuration directives can be stored in either a or section of httpd.conf or in a .htaccess file in the corresponding directory. Example configuration is given below : AuthXRadiusRetries 5 AuthXRadiusTimeout 2 AuthXRadiusAddServer "SERVERNAME.COM" "secret" AuthName "RADIUS" AuthBasicProvider xradius AuthType basic AuthBasicAuthoritative off require valid-user While configuring need to replace the SERVERNAME.COM with the machine name where the radius server is installed and running. 7)Start Apache. After completing the configuration of apache start apache using the following command. # /opt/hpws22/apache/bin/apachectl start Ensure that Apache works as expected. 9)Go to the browser you have configured and access the directory as specified in the httpd.conf file. Example URL for other configuration is www.servername.com/radius/test.html This should prompt you for UserName and Passwd for RADIUS authentication. Provide the same username and password as given during RADIUS environment setup. This should let you see the directory on authentication. On specifying any other password access should be denied. Note: If you want to use ssl then you need to uncomment the following in httpd.conf #Include conf/extra/httpd-ssl.conf TROUBLESHOOTING -------------------------------------- 1) Check if your RADIUS environment is set up properly. See section "Steps to configure mod_auth_xradius". 2) Ensure that the /etc/opt/aaa/users file is correct. 3) Ensure that the /etc/opt/aaa/clients file is correct. 4) Check the error_log with debug option on in httpd.conf. Change the line LogLevel warn To LogLevel debug and check the file /opt/hpws22/apache/logs/error_log for the errors. *************************************************************************** Legal Notices The information in this document is subject to change without notice. WARRANTY DISCLAIMER HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance or use of this material. RESTRICTED RIGHTS LEGEND Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies. Rights for non-DOD U.S. Government Department and Agencies are as set forth in FAR 52.227-19 (c)(1,2). COPYRIGHT NOTICES Copyright (c) 1998, Regents of the University of California All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the University of California, Berkeley nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. TRADEMARK NOTICES UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. ACKNOWLEDGEMENTS This product includes software developed by the Apache Software Foundation. This documentation is based on information from the Apache Software Foundation (http://www.apache.org).