Add documentation for the authenticate method

diff --git a/lib/Authen/Kerberos.pm b/lib/Authen/Kerberos.pm
index 215c59f3fb738560ced81ffe31c0d320791acd2e..7f0a40b33863c47cef95877237ae0e1b833a050a 100644 (file)
--- a/lib/Authen/Kerberos.pm
+++ b/lib/Authen/Kerberos.pm
@@ -62,7 +62,7 @@ bootstrap Authen::Kerberos $VERSION;
 __END__
 
 =for stopwords
-Allbery Heimdal keytabs libkrb5
+Allbery Heimdal keytabs libkrb5 TGT TGT-based keytab
 
 =head1 NAME
 
@@ -109,6 +109,33 @@ Kerberos error.
 
 =over 4
 
+=item authenticate(ARGS)
+
+Obtain initial credentials.  Currently, only authentication using keys
+stored in a keytab is supported.  ARGS should be a reference to a hash
+containing one or more of the following arguments:
+
+=over 4
+
+=item keytab
+
+The keytab containing the keys for the principal.
+
+=item principal
+
+The principal as which to authenticate.  This can be either the string
+representation of a principal or an Authen::Kerberos::Principal object.
+
+=item service
+
+The service for which to obtain session tickets.  If not given,
+authenticate() defaults to obtaining a ticket-granting ticket (TGT), which
+can be used to obtain other service tickets.  Normally this parameter is
+only necessary if the service to which one is authenticating is set to
+disallow TGT-based authentication (such as the password change service).
+
+=back
+
 =item keytab(KEYTAB)
 
 Open the given keytab and return a new Authen::Kerberos::Keytab object for