view release on metacpan or  search on metacpan

AuthenNTLM.pm  view on Meta::CPAN

use IPC::SysV qw(IPC_CREAT S_IRWXU SEM_UNDO);
use IPC::Semaphore;


sub lock
{
    my $class = shift ;
    my $key   = shift ;
    my $debug   = shift ;

    my $self = bless {debug => $debug}, $class ;
    $self->{sem} = new IPC::Semaphore($key, 1,
				      IPC_CREAT | S_IRWXU) or die "Cannot create semaphore with key $key ($!)" ;

    $self->{sem}->op(0, 0, SEM_UNDO,
                     0, 1, SEM_UNDO);
    print STDERR "[$$] AuthenNTLM: enter lock\n" if ($self -> {debug}) ;
    
    return $self ;
}

sub DESTROY
{
    my $self    = shift;

    $self->{sem}->op(0, -1, SEM_UNDO);
    print STDERR "[$$] AuthenNTLM: leave lock\n" if ($self -> {debug}) ;
}

1 ;

__END__

=head1 NAME

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

=head1 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>

=head1 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.

B<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, re...


=head1 CONFIGURATION


=head2 AuthType 

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

Set the realm for basic authentication

=head2 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.


=head2 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:

AuthenNTLM.pm  view on Meta::CPAN

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. 

=head2 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.

=head2 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.

=head2 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" 

=head2 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.


=head1 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 


=head2 $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.

=head2 $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.

=head2 $self -> verify_user ($r)

Should verify that the given user supplied the right credentials. Input:

=over

=item $self -> {basic}

Set when we are doing basic authentication

=item $self -> {ntlm}

Set when we are doing ntlm authentication

=item $self -> {username}

The username

=item $self -> {password}

The password when doing basic authentication

=item $self -> {usernthash}

The md4 hash when doing ntlm authentication

=item $self -> {userdomain}

The domain

=back

returns true if this is a valid user.

=head2 $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.

=head2 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