Provided by: libapache2-authenntlm-perl_0.02-5build3_amd64 bug

NAME

       Apache2::AuthenNTLM - Perform Microsoft NTLM and Basic User Authentication

SYNOPSIS

               <Location />
               PerlAuthenHandler Apache2::AuthenNTLM
               AuthType ntlm,basic
               AuthName test
               require valid-user

               #                    domain             pdc                bdc
               PerlAddVar ntdomain "name_domain1   name_of_pdc1"
               PerlAddVar ntdomain "other_domain   pdc_for_domain    bdc_for_domain"

               PerlSetVar defaultdomain wingr1
               PerlSetVar splitdomainprefix 1
               PerlSetVar ntlmdebug 1
               </Location>

DESCRIPTION

       The purpose of this module is to perform a user authentication via Microsoft's NTLM
       protocol. This protocol is supported by all versions of the Internet Explorer and is
       mainly useful for intranets. Depending on your preferences setting IE will supply your
       windows logon credentials to the web server when the server asks for NTLM authentication.
       This saves the user to type in his/her password again.

       The NTLM protocol performs a challenge/response to exchange a random number (nonce) and
       get back a md4 hash, which is built from the user's password and the nonce. This makes
       sure that no password goes over the wire in plain text.

       The main advantage of the Perl implementation is, that it can be easily extended to verify
       the user/password against other sources than a windows domain controller.  The defaultf
       implementation is to go to the domain controller for the given domain and verify the user.
       If you want to verify the user against another source, you can inherit from
       Apache2::AuthenNTLM and override it's methods.

       To support users that aren't using Internet Explorer, Apache2::AuthenNTLM can also perform
       basic authentication depending on its configuration.

       IMPORTANT: NTLM authentification works only when KeepAlive is on. (If you have set
       ntlmdebug 2, and see that there is no return message (type 3), check your httpd.conf file
       for "KeepAlive Off".  If KeepAlive Off, then change it to KeepAlive On, restart Apache,
       and test again).

CONFIGURATION

   AuthType
       Set the type of authentication. Can be either "basic", "ntlm" or "ntlm,basic" for doing
       both.

   AuthName
       Set the realm for basic authentication

   require valid-user
       Necessary to tell Apache to require user authentication at all. Can also used to allow
       only some users, e.g.

         require user foo bar

       Note that Apache2::AuthenNTLM does not perform any authorization, if the require xxx is
       executed by Apache itself. Alternatively you can use another (Perl-)module to perform
       authorization.

   PerlAddVar ntdomain "domain pdc bdc"
       This is used to create a mapping between a domain and both a pdc and bdc for that domain.
       Domain, pdc and bdc must be separated by a space. You can specify mappings for more than
       one domain.

       NOTE FOR WINDOWS ACTIVE DIRECTORY USERS: You must specify the DOMAIN for the pdc and/or
       bdc.  Windows smb servers will not accept ip address in dotted quad form.  For example,
       the SPEEVES domain pdc has an ip address of 192.168.0.2.  If you enter the ntdomain as:

       PerlAddVar ntdomain 192.168.0.2

       Then you will never be able be able to authenticate to the remote server correctly, and
       you will receive a "Can not get NONCE" error in the error_log.  You must specify it as:

       PerlAddVar ntdomain SPEEVES

       This means that you will need to resolve the DOMAIN locally on the web server machine.  I
       put it into the /etc/hosts file.

       For the complete run-down on this issue, check out:

       http://www.gossamer-threads.com/archive/mod_perl_C1/modperl_F7/%5BFwd:_Re:_Apache::AuthenNTLM-2.04_Problems..%5D_P104237/

   PerlSetVar defaultdomain
       Set the default domain. This is used when the client does not provide any information
       about the domain.

   PerlSetVar fallbackdomain
       fallbackdomain is used in cases where the domain that the user supplied isn't configured.
       This is useful in environments where you have a lot of domains, which trust each other,
       allowing you to always authenticate against a single domain, (removing the need to
       configure all domains available in your network).

   PerlSetVar ntlmauthoritative
       Setting the ntlmauthoritative directive explicitly to 'off' allows authentication to be
       passed on to lower level modules if AuthenNTLM cannot authenticate the user and the NTLM
       authentication scheme is used.  If set to 'on', which is the default, AuthenNTLM will try
       to verify the user and, if it fails, will give an Authorization Required reply.

   PerlSetVar basicauthoritative
       Setting the ntlmauthoritative directive explicitly to 'off' allows authentication to be
       passed on to lower level modules if AuthenNTLM cannot authenticate the user and the Basic
       authentication scheme is used.  If set to 'on', which is the default, AuthenNTLM will try
       to verify the user and if it fails will give an Authorization Required reply.

   PerlSetVar ntlmsemkey
       There are troubles when two authentication requests take place at the same time. If the
       second request starts, before the first request has successfully verified the user to the
       smb (windows) server, the smb server will terminate the first request. To avoid this
       Apache2::AuthenNTLM serializes all requests. It uses a semaphore for this purpose. The
       semkey directive set the key which is used (default: 23754).  Set it to zero to turn
       serialization off.

   PerlSetVar ntlmsemtimeout
       This set the timeout value used to wait for the semaphore. The default is two seconds.  It
       is very small because during the time Apache waits for the semaphore, no other
       authentication request can be sent to the windows server. Also Apache2::AuthenNTLM only
       asks the windows server once per keep-alive connection, this timeout value should be as
       small as possible.

   PerlSetVar splitdomainprefix
       If set to 1, $self -> map_user ($r) will return "username" else $self -> map_user ($r)
       will return "domain\username"

       Default is "domain\username"

   PerlSetVar ntlmdebug
       Set this to 1 if you want extra debugging information in the error log.  Set it to 2 to
       also see the binary data of the NTLM headers.

OVERRIDEABLE METHODS

       Each of the following methods takes the Apache object as argument. Information about the
       current authentication can be found inside the object Apache2::AuthenNTLM itself. To
       override the methods, create our own class which inherits from Apache2::AuthenNTLM and use
       it in httpd.conf e.g.

               PerlAuthenHandler Apache2::MyAuthenNTLM

   $self -> get_config ($r)
       Will be called after the object is setup to read in configuration informations.  The $r ->
       dir_config can be used for that purpose.

   $self -> get_nonce ($r)
       Will be called to setup the connection to the windows domain controller for $self ->
       {domain} and retrieve the nonce.  In case you do not authenticate against a windows
       machine, you simply need to set $self -> {nonce} to a 8 byte random string. Returns undef
       on error.

   $self -> verify_user ($r)
       Should verify that the given user supplied the right credentials. Input:

       $self -> {basic}
           Set when we are doing basic authentication

       $self -> {ntlm}
           Set when we are doing ntlm authentication

       $self -> {username}
           The username

       $self -> {password}
           The password when doing basic authentication

       $self -> {usernthash}
           The md4 hash when doing ntlm authentication

       $self -> {userdomain}
           The domain

       returns true if this is a valid user.

   $self -> map_user ($r)
       Is called before to get the user name which should be available as REMOTE_USER to the
       request. Default is to return DOMAIN\USERNAME.

   Example for overriding
       The following code shows the a basic example for creating a module which overrides the
       map_user method and calls AuthenNTLM's handler only if a precondition is met. Note: The
       functions preconditon_met and lookup_user do the real work and are not shown here.

           package Apache2::MyAuthenNTLM ;

           use Apache2::AuthenNTLM ;

           @ISA = ('Apache2::AuthenNTLM') ;

           sub handler ($$)
               {
               my ($self, $r) = @_ ;

               return Apache2::AuthenNTLM::handler ($self, $r) if (precondition_met()) ;
               return DECLINED ;
               }

           sub map_user

               {
               my ($self, $r) = @_ ;

               return lookup_user ($self->{userdomain}, $self->{username}) ;
               }

SUPPORT

       Speeves: Thanks to everyone that is helping to find bugs, etc. in this module.  Please,
       feel free to contact me and let me know of any strange things are going on with this
       module.  Also, please copy the modperl@perl.apache.org mailing list, as there are probably
       many others that are experiencing the same problems as you, and they may be able to return
       an answer faster than I can by myself.  Thanks :)

SEE ALSO

       An implementation of this module which uses cookies to cache the session.

       Apache-AuthCookieNTLM - Leo Lapworth http://search.cpan.org/~llap/Apache-AuthCookieNTLM/

AUTHOR

       G. Richter (richter@dev.ecos.de) Ported by Shannon Eric Peevey (speeves@unt.edu)

       Development of this package, versions 0.01-0.13 was sponsored by: Siemens:
       http://www.siemens.com