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

[raeburn]

raeburn		Tue Jan  4 02:02:14 2022 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Course_Prefs_Linkprotection.tex 
  Log:
  - Bug 6907. Documentation for 'Link protection' item in Course Settings used
    to specify LTI configuration for deep-link access from other systems.
  
  

Index: loncom/html/adm/help/tex/Course_Prefs_Linkprotection.tex
+++ loncom/html/adm/help/tex/Course_Prefs_Linkprotection.tex
\label{Course_Prefs_Linkprotection}

The Link protection panel is used to manage Learning Tool Interoperability (LTI) credentials used when the availability of specific resource(s) or folder(s) in
a LON-CAPA course needs to be restricted to deep-link-only access, via launch from another learning system.  A use case would be where another learning system supports
an online proctoring environment which students must use when accessing an exam folder in a LON-CAPA course.

Although configuration primarily uses the deeplink parameter available via the Parameter Manager for a specific resource or enclosing map/folder,
the options available when setting a value for that parameter can include the ID of an LTI launcher created using the course settings configuration menu reached via:
Settings $>$ Course Settings $>$ Display (``Link protection'' checked).

LTI launchers created in a course will be numbered incrementally (starting at 1), and each one will be listed in a drop-down list shown in the 
``Link protection'' box for the deeplink parameter itself, available when editing the deeplink parameter, if the currently checked radio button is: 
``course LTI launch''.

For each LTI launcher configured in a LON-CAPA course, the following need to be specified:
\begin{itemize}
\item Launcher Name
\item LTI Version
\item Nonce lifetime (s)
\item Key
\item Secret
\end{itemize}

The \textbf{Launcher Name} is used to identify an option shown in the ``course LTI launch'' drop-down list when setting a value for the deeplink parameter in the Parameter Manager.  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.

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.

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

The sole difference between the LTI launchers for deep-linking defined in a domain and those defined in a course is that for the former, a Course Coordinator
must obtain the key and secret from a Domain Coordinator, whereas for the latter a Course Coordinator will set the key and secret.  Note: the key and 
secret will be needed when configuring the LTI launch (in the other system) which is deep-linking to a specific folder or resource in the LON-CAPA course.
Although the details of the configuration on the launcher side will be specific to the particular system, the general approach is that an ``External Tool''
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.

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.

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}