Authen::Krb5::Simple version 0.32
===============================================================================
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.
You can also specify the location of the Kerberos include and libs directories
in the environment variables KRB5_INCLUDE and KRB5_LIB respectively.
Once that is done, then type the following:
perl Makefile.PL [-krb5_prompt]
make
make test
make install
Note: The optional "-krb5_prompt" argument will force the Makefile
generator to prompt for the location of the krb5 include and
lib directories.
In the absence of the "-krb5_prompt" and the KRB5_XXX environment
variable mentioned above, the module will make an attempt to figure
out the location of the Kerberos 5 include and lib files. If that
doesn't work, you will need to manually override using one of the
above methods.
DEPENDENCIES
This module requires the Kerberos 5 header and library files installed
on the local system.
Here is the Authen::Krb5::Simple man page:
---------------------------------------------------------------------------
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 => '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 returned if the *errstr* method 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.