view release on metacpan or  search on metacpan

lib/Apache2/AuthenNTLM/Cookie.pm  view on Meta::CPAN

  return "NTLM " . MIME::Base64::encode($packed, '');
}


sub ask_for_authentication {
  my $self = shift;

  my $r      = $self->{request};
  my $auth_type = $r->auth_type || 'NTLM,Basic';

  $self->add_auth_header('NTLM') 
    if $auth_type =~ /\bNTLM\b/i;
  $self->add_auth_header(sprintf 'Basic realm="%s"', $r -> auth_name || '')
    if $auth_type =~ /\bBasic\b/i;
}


sub add_auth_header {
  my ($self, $header) = @_;

  my $r           = $self->{request};
  my $header_name = $r->proxyreq ? 'Proxy-Authenticate' : 'WWW-Authenticate';
  $r->err_headers_out->add($header_name => $header);
}


sub is_ntlmauthoritative {
  my $self = shift;

  my $r      = $self->{request};
  my $config = $r->dir_config('ntlmauthoritative') || 'on';
  return $config =~ /^(on|1)$/i;
}


1; # End of Apache2::AuthenNTLM::Cookie


__END__

=head1 NAME

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

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

=head1 DESCRIPTION

This module extends  L<Apache2::AuthenNTLM> with a cookie mechanism.

The parent module L<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 
(L<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
L<http://davenport.sourceforge.net/ntlm.html#ntlmHttpAuthentication>.

=head1 CONFIGURATION

Configuration directives for NTLM authentication are 
just inherited from L<Apache2::AuthenNTLM>; see that module's
documentation. These are most probably all you need, namely
the minimal information for setting the handler, 
specifying the C<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 C<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 L<Apache2::Cookie> for explanation of variables
C<cookie_name>, C<domain>, C<expires>, and C<path>.
The only variables specific to the present module are

=over

=item refresh

This is the number of seconds after which the cookie becomes invalid
for authentication : it complements the C<expires> parameter.  The
C<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