.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Authen::Krb5::Simple 3pm"
.TH Authen::Krb5::Simple 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Authen::Krb5::Simple \- Basic user authentication using Kerberos 5
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  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\en";
\&  }
\&
\&  # Get the current default realm.
\&  #
\&  my $realm = $krb\->realm();
\&
\&  # Set the current realm
\&  #
\&  $krb\->realm(\*(AqMY.NEW.REALM\*(Aq);
\&
\&  # Create a new object pointing to another realm.
\&  #
\&  my $alt_krb = Authen::Krb5::Simple\->new(realm => \*(AqOTHER.REALM\*(Aq);
\&  ...
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Authen::Krb5::Simple\*(C'\fR 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.
.PP
\&\fBIt is important to note:\fR 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 \fIauthenticate\fR method is called.
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
\&\fBnew\fR
.Sp
.RS 4
The \fInew\fR method creates the \fIAuthen::Krb5::Simple\fR object.  It can take an
optional argument hash.  At present the only recognized argument is \f(CW\*(C`realm\*(C'\fR.
.Sp
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 \fIrealm\fR function
(see below).
.Sp
\&\fBExamples:\fR
.Sp
Using the default realm:
.Sp
.Vb 1
\&  my $krb = Authen::Krb5::Simple\->new();
.Ve
.Sp
specifying a realm:
.Sp
.Vb 1
\&  my $krb = Authen::Krb5::Simple\->new(realm => \*(Aqanother.realm.net\*(Aq);
.Ve
.RE
.SH METHODS
.IX Header "METHODS"
\&\fBauthenticate($user[@realm], \fR\f(CB$password\fR\fB)\fR
.Sp
.RS 4
the \fIauthenticate\fR method takes the user (or user@realm) and a password, and
uses kerberos 5 (the local systems installation) to authenticate the user.
.Sp
if the user/password is good, \fIauthenticate\fR will return a true value.
Otherwise, a false value is returned and the error code is stored in the
object.
.Sp
.Vb 5
\&  if($krb\->authenticate($user, $pw)) {
\&      print "$user authentication successful\en";
\&  } else {
\&      print "$user authentication failed: ", $krb\->errstr(), "\en";
\&  }
.Ve
.RE
.PP
\&\fBrealm( )\fR
.PP
\&\fBrealm(NEW.REALM)\fR
.Sp
.RS 4
The \fIrealm\fR 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.
.RE
.PP
\&\fBerrstr\fR
.Sp
.RS 4
The \fIerrstr\fR method will return the error message from the most recent
\&\fIauthentication\fR call.
.RE
.PP
\&\fBerrcode\fR
.Sp
.RS 4
The \fIerrstr\fR method will return the krb5 error code from the most recent
\&\fIauthentication\fR call.  This value will not be very useful.  Use the 
\&\fIerrstr\fR method to get a meaningful error message.
.RE
.SH BUGS
.IX Header "BUGS"
This version of \fIAuthen::Krb5::Simple\fR does not support null or
empty passwords.  If you pass an undefined value or empty string (\f(CW\*(Aq\*(Aq\fR)
as a password, \fIauthenticate\fR return false and set the error to indicate
that null or empty passwords are not supported.
.SH AUTHOR
.IX Header "AUTHOR"
Damien S. Stuart, <dstuart@dstuart.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, Kerberos5 documentation.