NAME

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

SYNOPSIS

         use Authen::Krb5::Simple;

         # Create a new Authen::Krb5::Simple object using
         # the system default realm.
         #
         my $krb = Authen::Krb5::Simple->new();

         # 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');

         # Create a new object pointing to another realm.
         #
         my $alt_krb = Authen::Krb5::Simple->new(realm => 'OTHER.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( )

       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 that 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 null or empty passwords.  If you
       pass an undefined value or empty string ('') as a password, authenticate return false and
       set the error to indicate that null or empty passwords are not supported.

AUTHOR

       Damien S. Stuart, <dstuart@dstuart.org>

SEE ALSO

       perl, Kerberos5 documentation.