--- loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex	2008/07/23 02:41:55	1.1
+++ loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex	2024/03/03 19:57:18	1.16
@@ -1,36 +1,87 @@
 \label{Domain_Configuration_LangTZAuth}
-The login page can be customized for your domain, by:
+Prior to LON-CAPA 2.7, default language and authentication type/argument
+were defined in the domain's entry in the domain.tab file. Those settings
+will continue to be used by servers in your domain until you have
+displayed and saved the Default authentication, language, timezone data
+table. Once that has been done, whenever values need to be determined
+for these settings in the domain they will be retrieved from the configuration.db
+file on the primary library server in your domain, which is where
+information saved from the {}``Domain Configuration'' data tables
+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.
+
+\textbf{Default domain configurations} can be assigned for: 
 
 \begin{itemize}
-\item uploading custom image files, 
-\item changing colors of text, links or backgrounds 
-\item enabling/disabling display of sepcific links 
+\item \textit{default language} used by users in your domain, unless overridden by
+a user preference
+\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 \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
+as well as EST5EDT, CST6CDT, MST7MDT, PST8PDT and HST (for Eastern,
+Central, Mountain, Pacific and Hawaii Timezones, which adjust for
+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 \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}
-Logos displayed in the login page configuration table are scaled down
-from the full size used in the login-page itself. 
 
+\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 
+defined in institutional data feeds.  Setting of user types via the Domain Configuration
+web GUI supersedes use of localenroll::inst\_usertypes().  Items that can be set are:
 
-\hfill{}
+\begin{itemize}
+\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}
 
-\noindent The following elements are configurable: 
+\textbf{Mapping for missing usernames via standard log-in} can be enabled for the domain via the same screen.
 
-\begin{itemize}
-\item Header image at the top of the page
-\item Main Logo centred in the upper part of the main panel 
-\item Domain logo in the lower left corner of the main panel 
-\item Header above the login panel - can also be set to use text (\char`\"{}Log
-in\char`\"{}) instead of an image. 
-\item Backgrond colors for the page itself, the main panel, and the left
-(side) panel. 
-\item Text color used for text on the page
-\item Enable/disable display of three links: 
+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.
+
+Two routines: \&unamemap\_rules() and \&unamemap\_check() in localenroll.pm (which is found in: 
+/home/httpd/lib/perl/ ) need to be customized to enable this functionality.
+There are stubs for both of them (with documentation) in the
+uncustomized template file: localenroll-std.pm in the same directory. 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.
 
-\begin{itemize}
-\item Course Catalog, for a catalog of courses; 
-\item Admin E-mail, for the e-mail address of the administrator; 
-\item New User, for users to create their own accounts. 
-\end{itemize}
-\item Default colors for links in the page, depending on status: either
-active, visited or default (if neither apply).
-\end{itemize}