--- loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex	2017/03/30 02:07:20	1.11
+++ loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex	2022/02/27 03:47:25	1.14
@@ -37,31 +37,6 @@ and might be for a load-balancer LON-CAP
 for a specific alias used for the domain.
 \end{itemize}
 
-\textbf{Domain settings for internal authentication} can also be set via the same screen.
-
-\begin{itemize}
-\item \textit{Encryption cost for bcrypt} (positive integer). Starting with 2.11.2, 
-bcrypt is used to encrypt the password for an internally authenticated user.
-The complexity of the encryption is determined by the bcrypt cost value. A higher 
-value means more complexity (and more time to validate a user's password). The
-cost needs to be a positive integer. If no value is set in a domain, a default
-of 10 will be used.
-\item \textit{Check bcrypt cost if authenticated}. When an internally authenticated user
-logins and the credentials are validated, the bcrypt cost used for the original
-encryption can be compared with the current domain default. If the cost for
-the stored encryption is less than the current domain setting, there are two 
-options - either allow login and update the stored encryption using the higher cost,
-or disallow login.  The default is not to compare the original cost with the
-current domain setting.
-\item \textit{Existing crypt-based switched to bcrypt if authenticated}. When an internally 
-authenticated user logs-in and the credentials are validated, if the stored
-credentials are currently encrypted with crypt, there is an option to update
-the stored encryption to use bcrypt, with or without backing-up the existing passwd
-file to a passwd.bak file.  The default is not to update the stored passwd file,
-so existing users who have crypt-based stored passwords will continue to do so 
-until such time as they change their password.
-\end{itemize}
-
 \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
@@ -76,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.
+