NAME

Apache::AuthCookieNTLM - NTLM (Windows domain) authentication with cookies

SYNOPSIS

'WhatEver' should be replaced with the AuthName you choose for this location's authentication.

    <Location />
        PerlAuthenHandler Apache::AuthCookieNTLM

        # NTLM CONFIG
        AuthType ntlm,basic
        AuthName WhatEver
        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 default_domain
        PerlSetVar ntlmdebug 1

        # COOKIE CONFIG - all are optional and have defaults
        PerlSetVar WhatEverName cookie_name
        PerlSetVar WhatEverExpires +5h
        PerlSetVar WhatEverPath /
        PerlSetVar WhatEverDomain yourdomain.com
        PerlSetVar WhatEverSecure 1
    </Location>

DESCRIPTION

As explained in the Apache::AuthenNTLM module, depending on the user's config, IE will supply your Windows logon credentials to the web server when the server asks for NTLM authentication. This saves the user typing in their windows login and password.

Apache::AuthCookieNTLM is an interface to Shannon Peevey's Apache::AuthenNTLM module. The main aim is to authenticate a user using their Windows login and authenticating against the Windows PDC, but to also store their login name into a cookie. This means that it can be accessed from other pages and stops the system having to authenticate for every request.

We did consider using Apache::AuthCookie to store the details in a cookie but since using NTLM is so that one can remove the need to login and is almost exclusively for intranets (as it needs access to the PDC), we decided it was feasible not to use it.

APACHE CONFIGURATION

Please consult the Apache::AuthenNTLM documentation for more details on the NTLM configuration.

'WhatEver' should be replaced with the AuthName you choose for this location's authentication.

PerlSetVar WhatEverName

Sets the cookie name. This will default to Apache::AuthCookieNTLM_WhatEver.

PerlSetVar WhatEverExpires

Sets the cookie expiry time. This defaults to being a session only cookie.

PerlSetVar WhatEverPath

Sets the path that can retrieve the cookie. The default is /.

PerlSetVar WhatEverDomain

Defaults to current server name, set to what ever domain you wish to be able to access the cookie.

PerlSetVar WhatEverSecure

Not set as default, set to 1 if you wish for cookies to only be returned to a secure (https) server.

PerlSetVar ntlmdebug

Setting this value means debugging information is shown in the apache error log, this value is also used for Apache::AuthenNTLM. Default to 0, set to 1 or 2 for more debugging info.

OVERRIDEABLE METHODS

choose_cookie_values()

The method can be overwritten to set the values stored in the cookie

Example for overriding

This is an example how to set your cookie values with whatever data you what, into our global variable $cookie_values which is a hash reference.

  package Apache::AuthCookieNTLM::MYAuthenNTLM;

  use Apache::AuthCookieNTLM;   
  use base ( 'Apache::AuthCookieNTLM' );

  sub choose_cookie_values {
    my $self = shift;

    # Save to global
    if ($cookie_values eq {} || $cookie_values->{username} ne $self->{username}) {
      $cookie_values->{username} = $self->{username};
      # look up from some package
      my $person = MyUserLookup_Package->new($self->{'username'});
      $cookie_values->{'email'} = $person->email();
      $cookie_values->{'shoe_size'} = $person->shoe_size();
    }
  }
  1;

AUTHOR

Leo Lapworth <llap@cuckoo.org>, Francoise Dehinbo