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 authentication 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 information.
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