Authentication Gateway HOWTO

1.1. Copyright Information

This document is copyrighted (c) 2001 Nathan Zorn. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html

If you have any questions, please contact <zornnh@musc.edu>

1.2. Disclaimer

No liability for the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility for that.

All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

You are strongly recommended to take a backup of your system before major installation and backups at regular intervals.

1.3. New Versions

The newest release of this document can be found at http://www.itlab.musc.edu/~nathan/authentication_gateway/ . Related HOWTOs can be found at the Linux Documentation Project homepage.

1.4. Credits

Jamin W. Collins

Kristin E Thomas

Logu (visolve.com)

1.5. Feedback

Feedback is most certainly welcome for this document. Without your submissions and input, this document wouldn't exist. Please send your additions, comments and criticisms to the following email address : <zornnh@musc.edu>.

2.1. Netfilter

The authentication gateway uses Netfilter and iptables to manage the firewall. Please see the Netfilter HOWTO .

2.2. Software for dynamic Netfilter rules.

One means to insert and remove Netfilter rules is to use pam_iptables. This is a pluggable authentication module (PAM) written by Nathan Zorn that can be found at http://www.itlab.musc.edu/~nathan/pam_iptables . This PAM module allows users to use ssh and telnet to authenticate to the gateway.

Another means to dynamically remove and create Netfilter rules is to use NocatAuth. NocatAuth can be found at http://nocat.net . NocatAuth provides a web client for authenticating to the gateway.

2.3. DHCP Server

The authentication gateway will act as the dynamic host configuration protocol (DHCP) server for the public network. It only serves those requesting DHCP services on the public network. I used the ISC DHCP Server .

2.4. Authentication mechanism

The gateway can use any means of PAM authentication. The authentication mechanism the Medical University of South Carolina uses is LDAP. Since LDAP was used for authentication, the pam modules on the gateway box were set up to use LDAP. More information can be found at http://www.padl.com/pam_ldap.html . PAM allows you to use many means of authentication. Please see the documentation for the PAM module you would like to use. For more information on other methods, see pam modules .

If NocatAuth is used, an authentication service needs to be setup. The NocatAuth authentication service supports authentication with LDAP,RADIUS,MySQL,and a password file. More information can be found at http://nocat.net/download/NoCatAuth/ .

2.5. DNS Server

The gateway box also serves as a DNS server for the public network. I installed Bind, and set it up as a caching nameserver. The rpm package caching-namserver was also used. This package came with Red Hat.

3.1. Netfilter Setup

To setup netfilter the kernel must be recompiled to include netfilter support. Please see the Kernel-HOWTO for more information on configuring and compiling your kernel.

This is what my kernel configuration looked like.

   #
   # Networking options
   #
   CONFIG_PACKET=y
   # CONFIG_PACKET_MMAP is not set
   # CONFIG_NETLINK is not set
   CONFIG_NETFILTER=y
   CONFIG_NETFILTER_DEBUG=y
   CONFIG_FILTER=y
   CONFIG_UNIX=y
   CONFIG_INET=y
   CONFIG_IP_MULTICAST=y
   # CONFIG_IP_ADVANCED_ROUTER is not set
   # CONFIG_IP_PNP is not set
   # CONFIG_NET_IPIP is not set
   # CONFIG_NET_IPGRE is not set
   # CONFIG_IP_MROUTE is not set
   # CONFIG_INET_ECN is not set
   # CONFIG_SYN_COOKIES is not set


   #   IP: Netfilter Configuration
   #   
   CONFIG_IP_NF_CONNTRACK=y
   CONFIG_IP_NF_FTP=y
   CONFIG_IP_NF_IPTABLES=y
   CONFIG_IP_NF_MATCH_LIMIT=y
   CONFIG_IP_NF_MATCH_MAC=y
   CONFIG_IP_NF_MATCH_MARK=y
   CONFIG_IP_NF_MATCH_MULTIPORT=y
   CONFIG_IP_NF_MATCH_TOS=y
   CONFIG_IP_NF_MATCH_TCPMSS=y
   CONFIG_IP_NF_MATCH_STATE=y
   CONFIG_IP_NF_MATCH_UNCLEAN=y
   CONFIG_IP_NF_MATCH_OWNER=y
   CONFIG_IP_NF_FILTER=y
   CONFIG_IP_NF_TARGET_REJECT=y
   CONFIG_IP_NF_TARGET_MIRROR=y
   CONFIG_IP_NF_NAT=y
   CONFIG_IP_NF_NAT_NEEDED=y
   CONFIG_IP_NF_TARGET_MASQUERADE=y
   CONFIG_IP_NF_TARGET_REDIRECT=y
   CONFIG_IP_NF_NAT_FTP=y
   CONFIG_IP_NF_MANGLE=y
   CONFIG_IP_NF_TARGET_TOS=y
   CONFIG_IP_NF_TARGET_MARK=y
   CONFIG_IP_NF_TARGET_LOG=y
   CONFIG_IP_NF_TARGET_TCPMSS=y
   

Once netfilter has been configured, turn on IP forwarding by executing this command.

   echo 1 > /proc/sys/net/ipv4/ip_forward
   

To make sure ip forwarding is enabled when the machine restarts add the following line to /etc/sysctl.conf.

   net.ipv4.ip_forward = 1
   

If NocatAuth is being used, you can skip to the NoCatAuth gateway setup section.

iptables needs to be installed. To install iptables either use a package from your distribution or install from source. Once the above options were compiled in the new kernel and iptables was installed, I set the following default firewall rules.

   iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
   iptables -A INPUT -i eth0 -m state --state NEW, INVALID -j DROP
   iptables -A FORWARD -i eth0 -m state --state NEW, INVALID -j DROP
   iptables -I FORWARD -o eth0 -j DROP
   iptables -I FORWARD -s 10.0.1.0/24 -d 10.0.1.1 -j ACCEPT
   

The above commands can also be put in an initscript to start up when the server restarts. To make sure the rules have been added issue the following commands:

   iptables -v -t nat -L
   iptables -v -t filter -L
   

To save these rules I used Red Hat's init scripts.

   /etc/init.d/iptables save
   /etc/init.d/iptables restart
   

Now the gateway box will be able to do network address translation (NAT), but it will drop all forwarding packets except those coming from within the public network and bound for the gateway.

3.2. Dynamic Netfilter rules.

This section describes how to setup the software needed to dynamically insert and remove Netfilter rules on the gateway.

     gcc -fPIC -c pam_iptables.c
     ld -x --shared -o pam_iptables.so pam_iptables.o
     

     cp pam_iptables.so /lib/security/pam_iptables.so
     

     mkdir /usr/local/auth-gw
     cp insFwall /usr/local/auth-gw
     

     session    required     /lib/security/pam_iptables.so 
     

     tar xvzf NocatAuth-x.xx.tar.gz
     

     cd NoCatAuth-x.xx
     make gateway
     

 
     ###### gateway.conf -- NoCatAuth Gateway Configuration.
     # 
     # Format of this file is: Directive Value, one per 
     # line. Trailing and leading whitespace is ignored. Any 
     # line beginning with a punctuation character is assumed to 
     # be a comment.
     
     Verbosity       10
     #we are behind a NAT so put the gateway in passive mode
     GatewayMode     Passive
     GatewayLog      /usr/local/nocat/nocat.log
     LoginTimeout    300
     
     ######Open Portal settings.
     HomePage        http://www.itlab.musc.edu/
     DocumentRoot    /usr/local/nocat/htdocs
     SplashForm      splash.html
     ###### Active/Passive Portal settings.
     TrustedGroups Any
     AuthServiceAddr egon.itlab.musc.edu
     AuthServiceURL  https://$AuthServiceAddr/cgi-bin/login
     LogoutURL       https://$AuthServiceAddr/forms/logout.html
     ###### Other Common Gateway Options.
     AllowedWebHosts egon.itlab.musc.edu
     ResetCmd        initialize.fw
     PermitCmd       access.fw permit $MAC $IP $Class 
     DenyCmd         access.fw deny $MAC $IP $Class 
     

     /usr/local/nocat/bin/gateway
     

3.3. DHCP Server Setup

I installed DHCP using the following dhcpd.conf file.

   subnet 10.0.1.0 netmask 255.255.255.0 {
   # --- default gateway
        option routers                  10.0.1.1;
        option subnet-mask              255.255.255.0;
        option broadcast-address        10.0.1.255;

        option domain-name-servers       10.0.1.1;      
        range   10.0.1.3 10.0.1.254;
        option time-offset              -5;     # Eastern Standard Time

        default-lease-time 21600;
        max-lease-time 43200;

    } 
    

The server was then run using eth1 , the interface to the public net.

    /usr/sbin/dhcpd eth1
    

3.4. Authentication Method Setup

Authentication with PAM and a NoCatAuth authentication service is described. Both examples are done with LDAP. Other means of authentication besides LDAP can be used. Please read the documentation for PAM and NoCatAuth to find the steps to use another authentication source.

     # Your LDAP server. Must be resolvable without using LDAP.
     host itc.musc.edu

     # The distinguished name of the search base.
     base dc=musc,dc=edu
     ssl no
     

    $ tar zvxf NoCatAuth-x.xx.tar.gz
    

    ###### authserv.conf -- NoCatAuth Authentication Service Configuration.
    #
    # Format of this file is: Directive Value, one per
    #   line. Trailing and leading whitespace is ignored. Any
    #   line beginning with a punctuation character is assumed to
    #   be a comment.

    Verbosity       10
    HomePage        http://www.itlab.musc.edu/
    DocumentRoot    /usr/local/nocat/htdocs
    # LDAP source
    DataSource LDAP
    LDAPHost authldap.musc.edu
    LDAPBase dc=musc,dc=edu

    UserTable       Member
    UserIDField     User
    UserPasswdField Pass
    UserAuthField   Status
    UserStampField  Created

    GroupTable      Network
    GroupIDField    Network
    GroupAdminField Admin
    MinPasswdLength 8
    
    # LocalGateway -- If you run auth service on the same subnet 
    #   (or host) as the gateway you need to specify the hostname 
    #   of the gateway. Otherwise omit it.  (Requires Net::Netmask)
    #
    # LocalGateway    192.168.1.7

    LoginForm       login.html
    LoginOKForm     login_ok.html
    FatalForm       fatal.html
    ExpiredForm     expired.html
    RenewForm       renew.html
    PassiveRenewForm renew_pasv.html
    RegisterForm    register.html
    RegisterOKForm  register_ok.html
    RegisterFields  Name URL Description

    UpdateForm      update.html
    UpdateFields    URL Description

    ###### Auth service user messages. Should be self-explanatory.
    #
    LoginGreeting   Greetings! Welcome to the Medical University of SC's Network.
    LoginMissing    Please fill in all fields!
    LoginBadUser    That e-mail address is unknown. Please try again.
    LoginBadPass    That e-mail and password do not match. Please try again.
    LoginBadStatus  Sorry, you are not a registered co-op member.

    RegisterGreeting    Welcome! Please enter the following information to register.RegisterMissing     Name, E-mail, and password fields must be filled in.
    RegisterUserExists  Sorry, that e-mail address is already taken. Are you already registered?
    RegisterBadUser     The e-mail address provided appears to be invalid. Did you spell it correctly?
    RegisterInvalidPass All passwords must be at least six characters long.
    RegisterPassNoMatch The passwords you provided do not match. Please try again.
    RegisterSuccess     Congratulations, you have successfully registered.

    UpdateGreeting      Enter your E-mail and password to update your info.
    UpdateBadUser       That e-mail address is unknown. Please try again.
    UpdateBadPass       That e-mail and password do not match. Please try again.
    UpdateInvalidPass   New passwords must be at least eight characters long.
    UpdatePassNoMatch   The new passwords you provided do not match. Please try again.
    UpdateSuccess       Congratulations, you have successfully updated your account.
    
    

 Include /usr/local/nocat/etc/authserv.conf 

3.5. DNS Setup

I installed the default version of Bind that comes with Red Hat 7.1, and the caching-nameserver RPM. The DHCP server tells the machines on the public net to use the gateway box as their nameserver.