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

[raeburn]

This is a MIME encoded message

--raeburn1217268766
Content-Type: text/plain

raeburn		Mon Jul 28 14:12:46 2008 EDT

  Added files:                 
    /loncom/html/adm/help/tex	
                             	Institutional_Integration_Format_Checks.tex 
  Log:
  - Document routines in localenroll.pm used in format rule defintion and checking.
  
  
--raeburn1217268766
Content-Type: text/plain
Content-Disposition: attachment; filename="raeburn-20080728141246.txt"


Index: loncom/html/adm/help/tex/Institutional_Integration_Format_Checks.tex
+++ loncom/html/adm/help/tex/Institutional_Integration_Format_Checks.tex
Format restrictions for usernames and student/employeeIDs for an institution,
and formats which may \emph{not} be used for e-mail addresses used
as usernames when users self-create accounts are defined in three
subroutines in localenroll.pm: \emph{username\_rules()}, \emph{id\_rules()},
and \emph{selfcreate\_rules()}. The three routines accept a similar
set of arguments, and return 'ok' in each case, if no error occurred.

\textbf{\large username\_rules} - Incoming data: three arguments

\begin{enumerate}
\item \$dom - domain
\item \$ruleshash - reference to hash containing rules (a hash of a hash)


keys of top level hash are short names (e.g., netid, noncredit); for
each key, value is a hash.

\begin{itemize}
\item desc => long name for rule
\item rule => description of rule
\item authtype => (krb5,krb4,int, or loc) authentication type for rule
\item authparm => authentication parameter for rule
\item authparmfixed => 1 if authparm used when creating user for rule must
be authparm
\item authmsg => Message to display describing authentication to use for
this rule
\end{itemize}
\item \$rulesorder - reference to array containing rule names in order to
be displayed
\end{enumerate}
At MSU, a NetID consists of eight characters or less, and will be
authenticated by Kerberos (version 5) in the MSU.EDU realm. The rule
itself is defined in \emph{username\_rules()}, and the code which
checks for compliance is in \emph{username\_check()}:

\begin{quotation}
\texttt{sub username\_rules \{}
\begin{quotation}
\texttt{my (\$dom,\$ruleshash,\$rulesorder) = @\_;}

\texttt{\%\{\$ruleshash\} = (}
\begin{quotation}
\texttt{netid => \{}
\begin{quotation}
\texttt{name     => 'MSU NetID',}

\texttt{desc     => 'Eight characters or less',}

\texttt{authtype => 'krb5',}

\texttt{authparm => 'MSU.EDU',}

\texttt{authparmfixed => '',}

\texttt{authmsg       => 'A new user with a username which matches
a valid MSU NetID will log-in using the MSU Net ID and MSU Net password.',}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{);}

\texttt{@\{\$rulesorder\} = ('netid');}

\texttt{return 'ok';}
\end{quotation}
\texttt{\}}
\end{quotation}
\textbf{\large id\_rules} - Incoming data: three arguments

\begin{enumerate}
\item \$dom - domain
\item \$ruleshash - reference to hash containing rules (a hash of a hash)keys
of top level hash are short names (e.g., studentID, employeeID); for
each key, value is a hash

\begin{itemize}
\item desc => long name for rule
\item rule => description of rule
\end{itemize}
\item \$rulesorder - reference to array containing rule names in order to
be displayed
\end{enumerate}
At MSU, studentIDs and employee IDs are eight digits prefaced by A
or Z. The rule itself is defined in \emph{id\_rules()}, and the code
which checks for compliance is in \emph{id\_check()}:

\begin{quotation}
\texttt{sub id\_rules \{}
\begin{quotation}
\texttt{my (\$dom,\$ruleshash,\$rulesorder) = @\_;}

\texttt{\%\{\$ruleshash\} = (}
\begin{quotation}
\texttt{studentID => \{}
\begin{quotation}
\texttt{name => 'MSU student PID',}

\texttt{desc => 'Letter A or a, followed by eight digits',}
\end{quotation}
\texttt{\},}

\texttt{facstaffID => \{}
\begin{quotation}
\texttt{name => 'MSU faculty/staff ID',}

\texttt{desc => 'Letter Z or z, followed by eight digits',}
\end{quotation}
\texttt{\},}
\end{quotation}
\texttt{);}

\texttt{@\{\$rulesorder\} = ('studentID','facstaffID');}

\texttt{return 'ok';}
\end{quotation}
\texttt{\}}
\end{quotation}
\textbf{\large selfcreate\_rules} - Incoming data: three arguments

\begin{enumerate}
\item \$dom - domain
\item \$ruleshash - reference to hash containing rules (a hash of a hash)


keys of top level hash are short names (e.g., msuemail); for each
key, value is a hash

\begin{itemize}
\item desc => long name for rule
\item rule => description of rule
\end{itemize}
\item \$rulesorder - reference to array containing rule names in order to
be displayed
\end{enumerate}
At MSU all users receive a Net ID (e.g., \emph{sparty}), and a corresponding
e-mail account: \emph{sparty@msu.edu}. So, at MSU the rules for e-mail
addresses to be used as LON-CAPA usernames prohibit e-mails such as
\emph{sparty@msu.edu}. In such cases, the user should log-in with
the sparty Net ID/password and request account creation for the username:
\emph{sparty}. The rule itself is defined in \emph{selfcreate\_rules()},
and the code which checks for compliance is in \emph{selfcreate\_check()}:

\begin{quotation}
\texttt{sub selfcreate\_rules \{}
\begin{quotation}
\texttt{my (\$dom,\$ruleshash,\$rulesorder) = @\_;}

\texttt{\%\{\$ruleshash\} = (}
\begin{quotation}
\texttt{msuemail => \{}

\texttt{name => 'MSU e-mail address ',}

\texttt{desc => 'netid@msu.edu',}
\end{quotation}
\texttt{\},}

\texttt{);}

\texttt{@\{\$rulesorder\} = ('msuemail');}

\texttt{return 'ok';}
\end{quotation}
\texttt{\}}
\end{quotation}
The corresponding routines which check for compliance with rules enabled
via Domain Configuration-> User Creation are \emph{username\_check()},
\emph{id\_check()}, and \emph{selfcreate\_check()}. The three routines
accept a similar set of four arguments, and return 'ok' in each case,
if no error occurred.

\begin{enumerate}
\item \$dom - domain (scalar)
\item \$uname (username\_check()), \$id (id\_check()) or \$selfcreatename
(selfcreate\_check())


- proposed username, id or self-created username being compared against
rules (scalar)

\item \$to\_check (reference to array of rule names to check)
\item \$resultshash (reference to hash of results) hash of results for rule
checked


keys are rule names - values are: 1 or 0 (for matched or unmatched)

\end{enumerate}
The routines used for checking rule compliance at MSU are as follows:

\textbf{\large username\_check} 

\begin{quotation}
\texttt{sub username\_check \{}
\begin{quotation}
\texttt{my (\$dom,\$uname,\$to\_check,\$resultshash) = @\_;}

\texttt{my \$outcome;}

\texttt{if (ref(\$to\_check) eq 'ARRAY') \{}
\begin{quotation}
\texttt{foreach my \$item (@\{\$to\_check\}) \{}
\begin{quotation}
\texttt{if (\$item eq 'netid') \{}
\begin{quotation}
\texttt{if (\$uname =\~{} /^\textbackslash{}w\{2,8\}\$/)
\{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 1;}
\end{quotation}
\texttt{\} else \{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 0;}
\end{quotation}
\texttt{\}}
\end{quotation}
\end{quotation}
\texttt{\}}

\texttt{\$outcome = 'ok';}
\end{quotation}
\texttt{\}}

\texttt{return \$outcome;}
\end{quotation}
\texttt{\}}
\end{quotation}
\textbf{\large id\_check} 

\begin{quotation}
\texttt{sub id\_check \{}
\begin{quotation}
\texttt{my (\$dom,\$id,\$to\_check,\$resultshash) = @\_;}

\texttt{my \$outcome;}

\texttt{if (ref(\$to\_check) eq 'ARRAY') \{}
\begin{quotation}
\texttt{foreach my \$item (@\{\$to\_check\}) \{}
\begin{quotation}
\texttt{if (\$item eq 'facstaffID') \{}
\begin{quotation}
\texttt{if (\$id =\~{} /^z\textbackslash{}d\{8\}\$/i)
\{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 1;}
\end{quotation}
\texttt{\} else \{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 0;}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\} elsif (\$item eq 'studentID') \{}
\begin{quotation}
\texttt{if (\$id =\~{} /^a\textbackslash{}d\{8\}\$/i)
\{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 1;}
\end{quotation}
\texttt{\} else \{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 0;}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}

\texttt{\$outcome = 'ok';}
\end{quotation}
\texttt{\}}

\texttt{return \$outcome;}
\end{quotation}
\texttt{\}}
\end{quotation}
\textbf{\large selfcreate\_check} 

\begin{quotation}
\texttt{sub selfcreate\_check \{}
\begin{quotation}
\texttt{my (\$dom,\$selfcreatename,\$to\_check,\$resultshash) = @\_;}

\texttt{my \$outcome;}

\texttt{if (ref(\$to\_check) eq 'ARRAY') \{}
\begin{quotation}
\texttt{foreach my \$item (@\{\$to\_check\}) \{}
\begin{quotation}
\texttt{if (\$item eq 'msuemail') \{}
\begin{quotation}
\texttt{if (\$selfcreatename =\~{} /^\textbackslash{}w\{2,8\}\textbackslash{}@msu\textbackslash{}.edu\$/)
\{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 1;}
\end{quotation}
\texttt{\} else \{}
\begin{quotation}
\texttt{\$resultshash->\{\$item\} = 0;}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}

\texttt{\$outcome = 'ok';}
\end{quotation}
\texttt{\}}

\texttt{return \$outcome;}
\end{quotation}
\texttt{\}}
\end{quotation}

--raeburn1217268766--