Authen::Krb5::Simple version 0.31
===============================================================================

The Authen::Krb5::Simple module provides a means to authenticate a user/password
using Kerberose 5.  Simply use this module and call its authenticate function
with a username (or user@KRB_REALM) and a password.  Detailed usage information
can be found in the module's perldoc.

INSTALLATION

To install this module edit the CONFIG file to set test username and password.
This is optional.  If no username and password is given, then the user auth
tests will be skipped.

Once that is done, then type the following:

   perl Makefile.PL  (answer the prompts)
   make
   make test
   make install

DEPENDENCIES

This module requires the Kerberos 5 header and library files.

---------------------------------------------------------------------------

NAME
    Authen::Krb5::Simple - Basic user authentication using Kerberos 5

SYNOPSIS
      use Authen::Krb5::Simple;

      my $krb = Authen::Krb5::Simple->new([realm => 'MY.KRB.REALM']);

      # Authenticate a user.
      #
      my $authen = $krb->authenticate($user, $password);

      unless($authen) {
          my $errmsg = $krb->errstr();
          die "User: $user authentication failed: $errmsg\n";
      }

      # Get the current default realm.
      #
      my $realm = $krb->realm();

      # Set the current realm
      #
      $krb->realm('MY.NEW.REALM');

DESCRIPTION
    The "Authen::Krb5::Simple" module provides a means to authenticate a
    user/password using Kerberos 5 protocol. The module's authenticate
    function takes a username (or user@kerberos_realm) and a password, and
    authenticates that user using the local Kerberos 5 installation. It was
    initially created to allow perl scripts to perform authentication
    against a Microsoft Active Directory (AD) server configured to accept
    Kerberos client requests.

    It is important to note: This module only performs simple
    authentication. It does not get, grant, use, or retain any kerberos
    tickets. It will check user credentials against the Kerberos server (as
    configured on the local system) each time the *authenticate* method is
    called.

CONSTRUCTOR
    new

        The *new* method creates the *Authen::Krb5::Simple* object. It can
        take an optional argument hash. At present the only recognized
        argument is "realm".

        If no realm is specified, the default realm for the local host will
        be assumed. Once set, the specified realm will be used for all
        subsequent authentication calls. The realm can be changed using the
        *realm* function (see below).

        Examples:

        Using the default realm:

          my $krb = Authen::Krb5::Simple->new();

        specifying a realm:

          my $krb = Authen::Krb5::Simple->new(realm => 'another.realm.net');

METHODS
    authenticate($user[@realm], $password)

        the *authenticate* method takes the user (or user@realm) and a
        password, and uses kerberos 5 (the local systems installation) to
        authenticate the user.

        if the user/password is good, *authenticate* will return a true
        value. Otherwise, a false value is returned and the error code is
        stored in the object.

          if($krb->authenticate($user, $pw)) {
              print "$user authentication successful\n";
          } else {
              print "$user authentication failed: ", $krb->errstr(), "\n";
          }
        
    realm([NEW.REALM])

        The *realm* method is used to set or get the current default realm.
        If an argument is passed to this method, the default realm is set to
        its value. If no argument is supplied, the current realm is
        returned.

    errstr

        The *errstr* method will return the error message from the most
        recent *authentication* call.

    errcode

        The *errstr* method will return the krb5 error code from the most
        recent *authentication* call. This value will not be very useful.
        Use the *errstr* method to get a meaningful error message.

BUGS
    This version of *Authen::Krb5::Simple* does not support empty passwords.
    If you pass an empty string ('') as a password, *authenticate* will
    print a warning and return false, but there will be no error code or
    string when *errstr* is called.

AUTHOR
    Damien S. Stuart, <damien.stuart@usi.net>

SEE ALSO
    perl, Kerberos5 documentation.

-------------------------------------------------------------------------------

COPYRIGHT AND LICENCE

Copyright (c) 2003 Damien S. Stuart. All rights reserved.
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.