--- 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. +