The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-AutoLogin-0.1
River stage zero No dependents
++
/ Apache::AutoLogin

NAME

Apache::AutoLogin - Automatic login module based on encrypted cookies for sites using basic authentication.

SYNOPSIS

  # In httpd.conf or .htaccess put it just
  # before your basic authentication module
  
  # It has the be invoked as a PerlAccessHandler,
  # because this is just the phase
  # before authentication!
  
  <Location />
        PerlModule Apache::AutoLogin
        PerlAccessHandler Apache::AutoLogin
        
        # Set the lifetime of the cookie in days
        
        PerlSetVar AutoLoginCookieLifetimeInDays "3"
        
        # The encryption key can have any length, but the longer the better
        
        PerlSetVar AutoLoginEncryptionKey "abcdefghijklmnopqrstuvwxyz123456"
        
        # set the logout page: Important, make
        # sure that you specify something
        # that gets not cached by proxies, or
        # else the cookie won't be invalidated.
        
        PerlSetVar AutoLoginLogoutPage "/logout.php"
        
        # The name of the cookie
        
        PerlSetVar AutoLoginAuthName "AutoLogin rulez"
        

        # Here comes the basic authentication
        # module of any flavour. Apache::AutoLogin
        # has been tested with AuthPAM and AuthLDAP
        
        AuthType Basic
        AuthName "Apache_AutoLogin example"
        AuthPAM_Enabled on
        require valid-user

  </Location>
  
  # In this example make sure logout.php
  # can be viewed by the client without authentication!
  
  <Location /logout.php>
        PerlModule Apache::AutoLogin
        PerlAccessHandler Apache::AutoLogin
        PerlSetVar AutoLoginCookieLifetimeInDays "3"
        ## Anything as a key, is not important, cause it will by a random key
        PerlSetVar AutoLoginEncryptionKey "abcdefghijklmnopqrstuvwxyz123456"
        PerlSetVar AutoLoginLogoutPage "/logout.php"
        PerlSetVar AutoLoginAuthName "AutoLogin rulez"

        Order allow,deny
        allow from all
        satisfy any
  </Location>

DESCRIPTION

Apache::AutoLogin is a mod_perl module for convenience of the users. It is NO authentication module so far, authentication is up to other auth basic modules of any flavour.

Apache::AutoLogin does basically the following:

If a client connects for the first time, grab it's request and look for an Apache::AutoLogin cookie. If there is such a cookie, extract the credentials, add them to the http headers for later use by the authentication module. During such a session, the client does not send any basic authentication credentials over the net.

If the client sends an authorization header, then one of two things happened: There was no cookie for supplying the credentials or the cookie or the credentials were invalid. Then we basically take the credentials from the client's header and store them into a cookie for later use. During such a session the client sents as usual basic credentials over the net.

If a client wants to log out, he / she has to invoke a predefined page of any flavour and we will set in invalid cookie to erase the credentials.

Who should use it?

Anyone who relies on basic authentication and does not want the users to authenticate everytime they point their browser to the restricted website. Especially useful for company intranets.

Security aspects

The cookie itself is AES256 encrypted using Crypt::Rjindael and features a md5 checksum of the data. Furthermore, some information about the client the cookie was issued for is stored as well (IP address, user-agent, hostname), which should make it more difficult to steal a cookie from someone. The cookie expires after a given time. This expiration date is stored in the encrypted part of the cookie as well. Each time one accesses the page, the cookie gets renewed.

Anyways, although cracking of the cookie is almost unfeasable with todays computing powers, be aware that this module is for convenience only. It does not give you any additional security (well a bit perhaps) over traditional basic authentication, where credentials are sent in plaintext over the net, because if there is no valid cookie, the client sents these credentials anyways. So for security's sake use ssl! The encryption of the cookie is done only for avoiding offline password sneaking on the client itself.

Although the cookie can be regarded as secure, the security of it's use stands and falls with the security of the computer it is stored on. If your users do not have personal accounts on their computers, forget about using it.

Apache configuration directives

All directives are passed in PerlSetVar.

AutoLoginCookieLifetimeInDays "3"

    Lifetime of the cookie in days.

AutoLoginEncryptionKey "abcdefghijklmnopqrstuvwxyz123456"

    The encryption key to use. Based on this key via md5 some fairly random 256 bit key will be generated. You may change it regularly.

AutoLoginLogoutPage "/logout.php"

    The logout URI. Make sure, that it does not get cached by any proxies or else the cookie cannot be invalidated and that this URI can be accessed without authentication!

AutoLoginAuthName "AutoLogin rulez"

    The name of the cookie.

License

Perl artistic license.

AUTHOR

Marcel M. Weber <lt>mmweber@ncpro.com<gt>

SEE ALSO

perl.