--- loncom/html/adm/help/tex/Course_Prefs_Linkprotection.tex	2022/01/04 02:02:14	1.1
+++ loncom/html/adm/help/tex/Course_Prefs_Linkprotection.tex	2022/02/22 19:38:42	1.3
@@ -27,7 +27,7 @@ The \textbf{LTI Version} will be 1.1. It
 
 A short \textbf{Nonce lifetime} can inhibit use of replay methods to circumvent link protection provided by LTI.  There should not be a need to set the value to other than the default of 300s.
 
-The \textbf{Key} and \textbf{Secret} should be kept secure, and will be needed when configuring the ``External Tool'' item in the other system which is linking to LON-CAPA.
+The \textbf{Key} and \textbf{Secret} should be kept secure, and will be needed when configuring the ``External Tool'' item in the other system which is linking to LON-CAPA.  There may be restrictions in place in the domain which specify a minimum or maximum length for a Secret, and also rules for its composition in terms of upper case, lower case, numbers, and/or special characters. If requirements are not met, an alert will be displayed indicating what is needed when ``Save Changes'' is pushed.  Once a Secret has been saved for a particular launcher, LON-CAPA will not display it again, so it is recommended to make a note of it, so it can be used in the other system.  To change an existing Secret check the ``Yes'' for ``Change?'' to make a textbox available for entering the new Secret. Note: the Key and Secret can only be submitted from a session on the course's home server, so if your session is on a different LON-CAPA server, a link to switch server will be shown in place of the textboxes for those two items. 
 
 A domain coordinator may have also configured LTI launchers for use in deep-linking, and if so, those will be available from a separate drop-down list
 displayed when setting the deeplink parameter when the currently checked radio button is: ``domain LTI launch''.
@@ -39,9 +39,23 @@ Although the details of the configuratio
 will be added in a course container on the other system, with an endpoint URL specified, along with the key and secret used to encrypt the payload sent with
 the request to the LON-CAPA endpoint URL.
 
-For this particular use case, information included in the payload besides the key, signature method, and LTI version will not be used, so the user will need to authenticate using the standard LON-CAPA username and password after the signed payload has been verified.  However, the user's LON-CAPA session will be recorded as having been launched from the deep-link target URL, if the access control setting for the deeplink parameter for the corresponding resource, or enclosing map/folder, is configured to support launch from the external system which provided the signed payload.
+If the domain has been configured to allow a username to be accepted from the signed payload, then for each LTI launcher there will also be a Yes/No option: \textbf{Use identity?}.  If `Yes' is selected then two (optional) settings can be specified:
+
+\begin{itemize}
+\item Source of username in LTI request
+\item Action if username does not match enrolled student
+\end{itemize}
+
+Deciding what to select as the source of the username requires knowing what the other learning system sends in the LTI Request.  Ideally, the other system will provide a preview feature for instructors to use to display items included in a launch request, and values set for them (for the previewer). In LON-CAPA, selecting ``User ID'' for the username source indicates the username will be whatever was assigned to the ``lis\_person\_sourcedid'' parameter, whereas selecting ``Email address'' means the username will be whatever was assigned to the ``lis\_person\_contact\_email\_primary'' parameter by the launch system.  If neither of those are appropriate then ``Other'' can be selected, and the appropriate parameter name in the LTI Request can be entered in the textbox.
+
+A username will only be accepted from the launch data for session creation in LON-CAPA if the corresponding user has already been assigned a student role, and no privileged role(s) in the target course in LON-CAPA.  What will happen if that condition is not met can either be to stop the launch, or to display the LON-CAPA login page, and allow a user to authenticate.  The second of those is the same behavior as seen if ``No'' had originally been selected for ``Use identity?'.
+
+Unlike LON-CAPA, other learning systems do not typically support multiple domains.  As a result when creating a user session based on a username included in the launch payload, the implicit assumption is made that the user's domain in LON-CAPA is the same as the course's domain. 
+
+In the case where usernames are not accepted from the launch payload, then each user will need to authenticate using the standard LON-CAPA username and password after the signed payload has been verified. After authentication the user's LON-CAPA session will still be recorded as having been launched from the deep-link target URL, as long as the access control setting for the deeplink parameter for the corresponding resource, or enclosing map/folder, is configured to support launch from the external system which provided the signed payload. 
+
+The endpoint LON-CAPA URL specified in the ``External Tool'' item in the other system will be composed of the following components: protocol or scheme (i.e., http or https), ://, hostname, /adm/launch, and the ``tiny URL' path to the target resource or folder.  If the LON-CAPA domain expects all access via a single server (i.e., a LON-CAPA load-balancer/portal node), then the hostname used should be the one assigned to the load-balancer.
 
-The URL should be composed of the following components: protocol or scheme (i.e., http or https), ://, hostname, /adm/launch, and the ``tiny URL' path to the target resource or folder.  If the LON-CAPA domain expects all access via a single server (i.e., a LON-CAPA load-balancer/portal node), then the hostname used should be the one assigned to the load-balancer.
 As the key and secret used for launch items (either in a course or a domain) will be unavailable to LON-CAPA nodes belonging to a different LON-CAPA domain, 
 if LTI link protection is to be used for deep-linked items, it is requirement that the endpoint URL include the hostname of a LON-CAPA server in the course's domain.