--- loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex	2020/01/08 19:03:55	1.12
+++ loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex	2022/02/27 01:43:14	1.13
@@ -51,3 +51,35 @@ web GUI supersedes use of localenroll::i
 \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.
+