The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-AuthenNTLM-2.04
River stage one • 1 direct dependent • 1 total dependent
++
/ Apache::AuthenNTLM

NAME

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

SYNOPSIS

        <Location />
        PerlAuthenHandler Apache::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 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 implementaion is, that it can be easily extented to verify the user/password against other sources than a windows domain controller. The default implementaion 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 Apache::AuthenNTLM and override it's methods.

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

IMPORTANT: NTLM authentification works only when KeepAlive is on.

CONFIGURATION

AuthType

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

AuthName

Set the realm for basic authetication

require valid-user

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

  require user foo bar

Note that Apache::AuthenNTLM does not perform any authorization, it the require xxx is executed by Apache itself. Alternativly 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 a pdc and bdc for that domain. Domain, pdc and bdc must be space separated. You can specify mappings for more than one domain.

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 enviroments where you have a lot of domains, which trust each other, so you can always authenticate against a single domain, so you don't 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 autheticate 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 Apache::AuthenNTLM serializes all requests. It uses a semaphore for this pupropse. The semkey directive set the key which is used (default: 23754). Set it to zero to turn serialization off.

PerlSetVar ntlmsemtimout

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 Apache::AuthenNTLM only asks the windows server once per keep-alive connection, this timeout value should be as small as possible.

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 Apache::AuthenNTLM itself. To override then methods, create our own class which inherits from Apache::AuthenNTLM and use it in httpd.conf e.g.

        PerlAuthenHandler Apache::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 Apache::MyAuthenNTLM ;

    use Apache::AuthenNTLM ;

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


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

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

    sub map_user

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

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

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