[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Domain_Configuration_LTI_Provider.tex

[raeburn]

raeburn		Mon Feb 21 21:29:11 2022 EDT

  Modified files:              
    /loncom/html/adm/help/tex	Domain_Configuration_LTI_Provider.tex 
  Log:
  - Update documentation for LTI Link Protection configuration in domain.
  
  
-------------- next part --------------
Index: loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex
diff -u loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex:1.2 loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex:1.3
--- loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex:1.2	Fri Dec 24 17:00:57 2021
+++ loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex	Mon Feb 21 21:29:11 2022
@@ -1,22 +1,92 @@
 \label{Domain_Configuration_LTI_Provider}
 
-LTI (Learning Tool Interoperability) Provider functionality in LON-CAPA may be used in the following ways (in order of integration from lowest to highest).
+LTI (Learning Tool Interoperability) Provider functionality is used in two ways in LON-CAPA.
+
+\begin{enumerate}
+\item Enforce deep-link only access to specific LON-CAPA course folder(s) or resource(s), via External Tool launch in a different learning management system.
+\item Provide basic LTI authentication, whereby a session can be established in LON-CAPA (the LTI Provider) for users already logged into a different system (the LTI Consumer), without re-authentication.
+\end{enumerate}
+
+To support these modes of operation the following can be set in a domain:
 
 \begin{itemize}
 
-\item Link protection for deep-link(s) to specific LON-CAPA course folder(s) or resource(s), whereby access to the resource(s) is only permitted via link(s) deployed as External Tool(s) available in particular LTI Consumer system(s).
+\item Encryption of shared secrets
+\item Rules for shared secrets
+\item Link Protectors
+\item Consumers
+
+\end{itemize}
+
+LTI employs a shared key and secret which the launcher (LTI Consumer) and the target (LTI Provider) will store locally. The key will be included in the (signed) payload included in a request created by the Consumer and sent to the Provider on launch.  The consumer will use the key and secret to verify that the contents of the payload has not been tampered with in transit.  As the payload can include the user's identity, which LON-CAPA can be configured to use to establish a session for that user, it is important that the secret for a particular LTI launch item remain private.  To assist with that, LON-CAPA offers the option to encrypt a secret when storing it on a domain's library server.
+
+Accordingly, an encryption key can be set on the primary library server in a LON-CAPA domain. That encryption key will be used to encrypt a shared secret when storing it, and to decrypt it when it needs to be used to verify payload integrity.
+
+\textbf{Link Protection}
 
-\item Basic LTI authentication, whereby a user authenticated by particular LTI Consumer system(s) can launch a user session in LON-CAPA without re-authentication.
+Link protection credentials can be configured at a domain level (by a Domain Coordinator), or at a course level (by a Course Coordinator), and the option is available to encrypt secret(s) at either or both of those levels.  In addition, secret(s) used for basic LTI authentication can also be set to be encrypted prior to storage in LON-CAPA.
 
-\item Creation of LON-CAPA user accounts, course containers, and assignment of roles in courses configured to occur automatically (as needed) on transfer of an authenticated user from a particular LTI Consumer system to LON-CAPA as the LTI Provider.
+Rules can be established for length and types of characters required in any secret assigned to a launch item.
 
+Link Protectors configured in a domain are numbered incrementally (starting at 1).
+  
+For each Link Protector the following need to be specified:
+\begin{itemize}
+\item Launcher Name
+\item LTI Version
+\item Nonce lifetime (s)
+\item Key
+\item Secret
 \end{itemize}
 
-With the last of these (the closest integration) the need for user management within a LON-CAPA course can be eliminated because users and roles can be created automatically when a user in a course in the Consumer system is transferred to the LON-CAPA environment.  Pass-back of grades from LON-CAPA to the consumer can also be configured.
+The \textbf{Launcher Name} is used to identify an option shown in the ``domain LTI launch'' drop-down list when setting a value for the deeplink parameter in the Parameter Manager in a course.  Its value can be changed without impacting the behavior of the link, as LON-CAPA internally stores the launcher item associated with a deep-link using the unique numeric identifier assigned to the launcher item when it was first created.
+
+The \textbf{LTI Version} will be 1.1. It is expected that newer versions will also be supported in the future.
 
-The extent of interoperability between Consumer and Provider, and also the behavior of a LON-CAPA course session when launched from the Consumer, are determined by the Provider configuration(s) for Consumer(s) in a LON-CAPA domain. LTI Provider configurations may be set for multiple Consumers using a unique key and secret for each. Similarly, multiple configurations (with different levels of integration) can be set for an individual Consumer, again using a unique key and secret for each configuration. 
+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.
 
-Categories for configuration for each Consumer instance are as follows: 
+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. 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 a domain's primary library 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.
+
+For each Link Protector 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.
+
+Although the `Use identity?' option may be set to 'Yes' for a Link Protector item configured in a domain, whether or not the username included in launch data will be accepted in a particular course can be controlled on a course-by-course basis by a Domain Coordinator.
+
+The ``Course/Community defaults'' item \ref{Domain_Configuration_Course_Defaults} includes a Yes/No option for: ``Student username in LTI launch of deep-linked URL can be accepted without re-authentication''.  A Domain Coordinator can use:
+Main Menu $>$ Set domain configuration $>$ View or modify a course or community to select a course, and then use the ``View/Modify re-authentication requirement for LTI launch of deep-linked item'' link to override the domain default for a specific course.  
+
+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.
+
+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.
+
+Following the hostname, the remainder of the URL  will have the format: /adm/launch/tiny/\$domain/uniqueID, where /tiny/\$domain/uniqueID is a shortened URL,
+unique to the particular folder or resource in the specific course.
+
+Course Coordinators can generate shortened URLs for items in a course by using:
+Course Editor $>$ Content Utilities $>$ ``Display/Set Shortened URLs for Deep-linking''; see: Short URLs section \ref{Docs_Short_URLs}
+
+\textbf{Consumers}
+
+As noted above, use of link protectors defined either in a domain or in a course, requires that the user already has a LON-CAPA user account, and a student role assigned in a LON-CAPA course.
+
+If instead, more complete integration is desired between the remote (launcher) system and LON-CAPA, then a LTI Consumer item can be configured using the fourth panel: ``Consumers'' in the ``LTI Link Protection and LTI Consumers'' box. 
+
+The extent of interoperability between Consumer and Provider, and also the behavior of a LON-CAPA course session when launched from the Consumer, are determined by the Provider configuration(s) for Consumer(s) in a LON-CAPA domain. LTI Provider configurations may be set for multiple Consumers using a unique key and secret for each. Similarly, multiple configurations (with different levels of integration) can be set for an individual Consumer, again using a unique key and secret for each configuration.
+
+The need for user management within a LON-CAPA course can be eliminated because users and roles can be created automatically when a user in a course in the Consumer system is transferred to the LON-CAPA environment.  Pass-back of grades from LON-CAPA to the consumer can also be configured.
 
 \begin{itemize}
 
@@ -48,12 +118,10 @@
 The ``Required settings'' include seven items:
 Consumer, LTI Version, Nonce lifetime (s), User`s identity sent, Course's identity sent, Key and Secret.
 
-For each Consumer, a key and secret (which will be provided by a Consumer administrator) should be stored securely.  Within LON-CAPA the values for those two will be stored in a configuration file, separate from the other domain configuration settings, and when needed should be transferred from the library node to access node(s) in the domain using a lonc/lond connection for which exchange of the shared encryption key is via an SSL tunnel.   In addition, creation of a LON-CAPA user session in a domain as a result of launch from an LTI Consumer is only permitted on LON-CAPA nodes belonging to the same ``internet'' domain as the domain's library server.  The ``internet'' domain is the last entry in the record for a particular node in the /home/httpd/lonTabs/hosts.tab file on a LON-CAPA server.  Accordingly, the target URL defined in the External Tool configuration on another Learning Management System (the Consumer) should include the hostname of a node in an appropriate LON-CAPA doma
 in.
+Creation of a LON-CAPA user session in a domain as a result of launch from an LTI Consumer is only permitted on LON-CAPA nodes belonging to the same ``internet'' domain as the domain's library server.  The ``internet'' domain is the last entry in the record for a particular node in the /home/httpd/lonTabs/hosts.tab file on a LON-CAPA server.  Accordingly, the target URL defined in the External Tool configuration on another Learning Management System (the Consumer) should include the hostname of a node in an appropriate LON-CAPA domain.
 
 If the LTI Provider setting for a Consumer has ``User`s identity sent'' set to ``No'', then user information included in the LTI payload (signed by the Consumer using the key and secret) will not be used, and a user session will not be created automatically in LON-CAPA.
 
-A use case for this mode of operation would be one where content in a LON-CAPA course is deep-linked for access from the Consumer, and both Consumer and Provider authenticate users with a common Single Sign On (SSO) system for the institution, and user accounts (and course enrollment) are already in place for the user`s username in both Consumer and Provider.  Note: an alternative to using the LTI Provider domain configuration to support this type of deep-linking to LON-CAPA content, is for a Course Coordinator to use the ``Link protection'' settings item in a course to set LTI Version, Nonce lifetime (s), key and secret for a specific Consumer.
-
 In the case where LON-CAPA will accept user identity information from launch in the Consumer, then the ``Course's identity sent'' item can optionally also be set to ``Yes''. When user identity is accepted the next five categories listed above will be available for configuration for the Consumer, although which ones are applicable depends on the capabilities of the Consumer.  When course context information is accepted the remaining four categories listed above will also be available (applicability also depends on Consumer capabilities). 
 
 When both User and Course identity are accepted from the Consumer, the configuration for each Consumer will determine who (if anyone) may:
@@ -110,5 +178,3 @@
 
 When starting out with a new LON-CAPA domain there will be one user account, namely a filesystem-authenticated user with an assigned Domain Coordinator role, originally created by running the make\_domain\_coordinator.pl script on the command line.  If that user accesses LON-CAPA via the standard log-in page in the web GUI, i.e., /adm/login, and selects a Domain Coordinator role, and uses Main Menu $>$ Set domain configuration $>$ Display (LTI Provider checked), to configure LTI Provider support, all subsequent access by other users can be from other LTI Consumer(s).
 
-
-