/ 
Apache2-AuthenNTLM-Cookie-1.02
River stage zero No dependents
/ Apache2::AuthenNTLM::Cookie

NAME

Apache2::AuthenNTLM::Cookie - Store NTLM identity in a cookie

SYNOPSIS

<Location /my/secured/URL>
  PerlAuthenHandler Apache2::AuthenNTLM::Cookie
  AuthType ntlm
  PerlAddVar ntdomain "domain primary_domain_controller other_controller"
  ...    # see other configuration params in Apache2::AuthenNTLM
</Location>

DESCRIPTION

This module extends Apache2::AuthenNTLM with a cookie mechanism.

The parent module Apache2::AuthenNTLM performs user authentication via Microsoft's NTLM protocol; thanks to this mechanism, users are automatically recognized from their Windows login, without having to type a username and password. The server does not have to be a Windows machine : it can be any platform, provided that it has access to a Windows domain controller. On the client side, both Microsoft Internet Explorer and Mozilla Firefox implement the NTLM protocol.

The NTLM handshake involves several packet exchanges, and furthermore requires serialization through an internal semaphore. Therefore, in order to improve performance, the present module saves the result of that handshake in a cookie, so that the next request gets an immediate answer.

A similar module was already published on CPAN for Apache1 / modperl1 (Apache::AuthCookieNTLM). The present module is an implementation for Apache2 / modperl2, and has a a different algorithm for cookie generation, in order to prevent any attempt to forge a fake cookie.

Details about the NTLM authentication protocol can be found at http://davenport.sourceforge.net/ntlm.html#ntlmHttpAuthentication.

CONFIGURATION

Configuration directives for NTLM authentication are just inherited from Apache2::AuthenNTLM; see that module's documentation. These are most probably all you need, namely the minimal information for setting the handler, specifying the AuthType and specifying the names of domain controllers :

<Location /my/secured/URL>
  PerlAuthenHandler Apache2::AuthenNTLM::Cookie
  AuthType ntlm
  PerlAddVar ntdomain "domain primary_domain_controller other_controller"
</Location>

In addition to the inherited directives, some optional PerlSetVar directives allow you to control various details of cookie generation :

PerlSetVar cookie_name my_cookie_name    # default is NTLM_AUTHEN
PerlSetVar domain      my_cookie_domain  # default is none
PerlSetVar expires     my_cookie_expires # default is none
PerlSetVar path        my_cookie_path    # default is none
PerlSetVar refresh     some_seconds      # default is 14400 (4 hours)
PerlSetVar secret      my_secret_string  # default from stat(config file)

See Apache2::Cookie for explanation of variables cookie_name, domain, expires, and path. The only variables specific to the present module are

refresh

This is the number of seconds after which the cookie becomes invalid for authentication : it complements the expires parameter. The expires value is a standard HTTP cookie mechanism which tells how long a cookie will be kept on the client side; its default value is 0, which means that this is a session cookie, staying as long as the browser is open. But if the Windows account gets disabled, the cookie will never reflect the new situation : therefore we must impose a periodic refresh of the cookie. The default refresh value is 14400 seconds (four hours).

secret

This is a secret phrase for generating a SHA1 digest that will be incorporated into the cookie. The digest also incorporates the username and cookie creation time, and is checked at each request : therefore it is impossible to forge a fake cookie without knowing the secret.

The default value for the secret is the concatenation of modification time and inode of the httpd.conf file on the server; therefore if the configuration file changes, authentication cookies are automatically invalidated.

SPECIAL NOTE ABOUT INTERNET EXPLORER

Microsoft Internet Explorer (MSIE) has an "optimization" when sending POST requests to an NTLM-secured site : the browser does not send the request body because it expects to receive a 401 HTTP_UNAUTHORIZED response, and then would send the body only at the second request. This is a problem with the present module, because if authorization is granted on the basis of a cookie, instead of NTLM handshake, then control goes to the HTTP response handler ... but that handler gets no parameters since the request body is empty !

One way to fix the problem is to set the registry entry HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/DisableNTLMPreAuth; but this is only feasible if one has control over the registry settings of all clients. Otherwise, the present module will forge a fake "NTLM type2" message, so that Internet will try again, sending a new NTLM type3 request with a proper body. See http://lists.samba.org/archive/jcifs/2006-September/006554.html for more details about this issue.

AUTHOR

Laurent Dami, <la_____.da__@etat.ge.ch>

BUGS

Please report any bugs or feature requests to bug-apache2-authenntlm-cookie at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache2-AuthenNTLM-Cookie. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Apache2::AuthenNTLM::Cookie

You can also look for information at:

TESTING NOTE

This module has no tests ... because I didn't manage to write command-line tests that would successfully load the APR dynamic libraries. Any hints welcome! Nevertheless, the module has been successfully tested on Apache2.2/modperl2/solaris.

COPYRIGHT & LICENSE

Copyright 2008,2010 Laurent Dami, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.