[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Institutional_Integration_Authentication.tex

[raeburn]

raeburn		Tue Jul 29 13:35:13 2008 EDT

  Added files:                 
    /loncom/html/adm/help/tex	
                             	Institutional_Integration_Authentication.tex 
  Log:
  - Document customization of localauth.pm 
  
  

Index: loncom/html/adm/help/tex/Institutional_Integration_Authentication.tex
+++ loncom/html/adm/help/tex/Institutional_Integration_Authentication.tex
\label{Institutional_Integration_Authentication}
When a user is assigned an authentication type of {}``Local authentication''
, the perl module /home/httpd/lib/perl/localauth.pm will be used to
evaluate the user's credentials. The documentation included in the
stub provided with a LON-CAPA installation describes the basic operation
of localauth.pm

The localauth routine receives four arguments (in the order: two required,
one optrional, another required).

\begin{enumerate}
\item the username the user types in.
\item the password the user typed in.
\item optional information stored when the authentication mechanism was
specified for the user ({}``Local authentication with argument: ....{}``)
\item the domain the user typed in.
\end{enumerate}
The routine will return 1 if the user is authenticated and 0 otherwise,
and it can optionally return a negative value for an error condition.
This negative value will be logged along with the username used in
the failed authentication which resulted in the error condition.

A common use of localauth.pm is to connect with an LDAP service.

\begin{quotation}
\texttt{package localauth;}

\texttt{use strict;}

\texttt{use Net::LDAP;}

\texttt{use Net::LDAPS;}

\texttt{sub localauth \{}
\begin{quotation}
\texttt{my (\$username,\$password) = @\_;}

\texttt{my \$ldap\_host\_name = ''; \# insert the host name of your
ldap server, e.g., ldap.msu.edu}

\texttt{my \$ldap\_ca\_file\_name = ''; \# insert the ldap certificate
filename - include absolute path}

\texttt{\# certificate is required if you wish to encrypt the password.}

\texttt{\# e.g., /home/http/perl/lib/local/ldap.certificate}

\texttt{my \$ldap\_search\_base = ''; \# ldap search base, this might
be set to 'o=msu.edu'.}

\texttt{my \$ldap = Net::LDAPS->new(}
\begin{quotation}
\texttt{\$ldap\_host\_name, }

\texttt{verify => 'require', \# 'require' -> a certificate is needed,
-> 'none' if no certificate used}

\texttt{cafile => \$ldap\_ca\_file\_name,}
\end{quotation}
\texttt{);}

\texttt{if (!(defined(\$ldap))) \{}
\begin{quotation}
\texttt{return (0);}
\end{quotation}
\texttt{\}}

\texttt{\$ldap->bind;}

\texttt{my \$search\_string = '(uid='.\$username.')';}

\texttt{my \$mesg = \$ldap->search (}
\begin{quotation}
\texttt{base => \$ldap\_search\_base,}

\texttt{filter => \$search\_string,}

\texttt{attrs => {[}'dn'] ,}
\end{quotation}
\texttt{);}

\texttt{if (\$mesg->code) \{}
\begin{quotation}
\texttt{\$ldap->unbind;}

\texttt{\$ldap->disconnect;}

\texttt{return (0);}
\end{quotation}
\texttt{\}}

\texttt{my @entries = \$mesg->all\_entries;}

\texttt{if (@entries > 0) \{}
\begin{quotation}
\texttt{\$ldap->unbind;}

\texttt{\$ldap->disconnect;}

\texttt{return (0);}
\end{quotation}
\texttt{\}}

\texttt{\$mesg = \$ldap->bind (}
\begin{quotation}
\texttt{dn => \$entries{[}0]->dn,}

\texttt{password => \$password,}
\end{quotation}
\texttt{);}

\texttt{\$ldap->unbind;}

\texttt{\$ldap->disconnect;}

\texttt{if (\$mesg->code) \{}
\begin{quotation}
\texttt{return (0)}
\end{quotation}
\texttt{\}}

\texttt{return (1);}
\end{quotation}
\texttt{\}}

\texttt{1;}
\end{quotation}