--- loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex 2015/03/26 18:49:02 1.10
+++ loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex 2022/02/27 03:47:25 1.14
@@ -10,19 +10,19 @@ information saved from the {}``Domain Co
is stored. Any information in the domain.tab file will no longer be
consulted, except by servers running pre-2.7 versions of LON-CAPA.
-Default domain configurations can be assigned for:
+\textbf{Default domain configurations} can be assigned for:
\begin{itemize}
-\item default language used by users in your domain, unless overridden by
+\item \textit{default language} used by users in your domain, unless overridden by
a user preference
-\item default authentication type for new users in the domain. You will
+\item \textit{default authentication type} for new users in the domain. You will
need to set the default authentication if you intend to allow a user
to create a LON-CAPA account if the user successfully authenticated
via a central service at your institution (e.g., Kerberos), but is
without a LON-CAPA account. The default authentication is also the
default offered when Course Coordinators or Authors create new accounts,
assuming user creation is permitted in these contexts.
-\item default timezone - this will be the timezone used when showing any
+\item \textit{default timezone} - this will be the timezone used when showing any
times in your domain, unless overridden at a course level, by a course-wide
timezone. The timezones available are mostly in the form Continent/City,
although for the USA there are some in the form America/State/City
@@ -31,13 +31,13 @@ Central, Mountain, Pacific and Hawaii Ti
daylight savings as appropriate). If no default timezone is set times
will be displayed according to the timezone of the server hosting
the user's LON-CAPA session.
-\item portal/default URL - starting with LON-CAPA 2.10, a default URL can
+\item \textit{portal/default URL} - starting with LON-CAPA 2.10, a default URL can
be specified. This URL will be included in e-mail sent to confirm self-enrollment etc.
and might be for a load-balancer LON-CAPA server, or in the case of a multi-domain server,
for a specific alias used for the domain.
\end{itemize}
-Domain configurations can also be set for institutional user types via the same screen.
+\textbf{Institutional user types} can also be defined for the domain via the same screen.
Prior to LON-CAPA 2.11, institutional user types were defined in the \&inst\_usertypes
subroutine in localenroll.pm, which would be customized for consistency with types
@@ -45,10 +45,41 @@ defined in institutional data feeds. Se
web GUI supersedes use of localenroll::inst\_usertypes(). Items that can be set are:
\begin{itemize}
-\item Internal ID (e.g., faculty)
-\item Name Displayed (e.g., Faculty/Academic Staff)
-\item Order (Listing order, 1 through N, when the type is to be selected from a list).
-\item Whether status type can also be assigned to a non-institutional user with an e-mail
- address as username
+\item \textit{Internal ID} (e.g., faculty)
+\item \textit{Name Displayed} (e.g., Faculty/Academic Staff)
+\item \textit{Order} (Listing order, 1 through N, when the type is to be selected from a list).
+\item \textit{Assignment to ``email-based'' usernames} Whether status type can also be assigned to a non-institutional user with an e-mail address as username
\end{itemize}
+\textbf{Mapping for missing usernames via standard log-in} can be enabled for the domain via the same screen.
+
+For a user who logs-in to LON-CAPA via the standard log-in screen, customization is available to support credentials
+checking with an alternate username (but same password) if the username, as originally entered by the user, should
+be altered in a predictable way, to make it consistent with the format expected for usernames in the domain.
+
+An example is where an email address is supplied as the username by the user, but the part of the email address
+which precedes the @ in the email address is what is actually used in LON-CAPA for the user's username.
+
+A complication is the fact that a domain may support both types of username, e.g., userID, and userID@example.tld,
+as legitimate usernames for different types of user. For example the usernames for official users may look like: userID,
+but privileged users may also create user accounts for guest users (including ``fictitous'' usernames for themselves, to
+use to test course behavior as a student) which look like: userID@example.tld.
+
+To accommodate that possibility, LON-CAPA will first attempt to authenticate the username and password, but if a user
+does not exist for the supplied username in the domain, can then see if a ``real'' username can be extracted from
+the one supplied, and make a second attempt to authenticate using the derived username with the password. Accordingly,
+authentication would fail for: userID@example.tld if that user did not exist, but might succeed for userID if that user
+did exist, and the password supplied matched what was expected.
+
+To enable this functionality requires customizing two routines in /home/httpd/lib/perl/localenroll.pm:
+&unamemap\_rules() and &unamemap\_check(). There are stubs for both of them (with documentation) in the
+uncustomized template file: /home/httpd/lib/perl/localenroll-std.pm. Restart of loncontrol is required
+after making changes to localenroll.pm.
+
+Once &unamemap\_rules() contains at least one rule, then the ``Default authentication/language/timezone/portal/types''
+domain configuration will include a checkbox for at least one rule in ``Available conversions'' listed in the
+``Mapping for missing usernames via standard log-in'' section. Checking the checkbox and pushing ``Save Changes''
+will make the corresponding conversion for that rule, as coded in &unamemap\_check(), available to create
+a derived username for a second authentication attempt, if the original username did not exist, but matched
+the required format for the conversion.
+