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

[raeburn]

raeburn		Mon Nov 29 15:50:04 2021 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Domain_Configuration_LTI_Provider.tex 

  Modified files:              
    /doc/loncapafiles	loncapafiles.lpml 
  Log:
  - Documentation for LTI Provider configuration (work in progress).
  
  
-------------- next part --------------
Index: doc/loncapafiles/loncapafiles.lpml
diff -u doc/loncapafiles/loncapafiles.lpml:1.1014 doc/loncapafiles/loncapafiles.lpml:1.1015
--- doc/loncapafiles/loncapafiles.lpml:1.1014	Mon Nov 29 15:48:07 2021
+++ doc/loncapafiles/loncapafiles.lpml	Mon Nov 29 15:50:03 2021
@@ -2,7 +2,7 @@
  "http://lpml.sourceforge.net/DTD/lpml.dtd">
 <!-- loncapafiles.lpml -->
 
-<!-- $Id: loncapafiles.lpml,v 1.1014 2021/11/29 15:48:07 raeburn Exp $ -->
+<!-- $Id: loncapafiles.lpml,v 1.1015 2021/11/29 15:50:03 raeburn Exp $ -->
 
 <!--
 
@@ -3762,6 +3762,7 @@
 Domain_Configuration_LangTZAuth.tex;
 Domain_Configuration_Load_Balancing.tex;
 Domain_Configuration_Login_Page.tex;
+Domain_Configuration_LTI_Provider.tex;
 Domain_Configuration_LTI_Tools.tex;
 Domain_Configuration_Passwords.tex;
 Domain_Configuration_Quotas.tex;

Index: loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_LTI_Provider.tex
\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).

\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 Basic LTI authentication, whereby a user authenticated by particular LTI Consumer system(s) can launch a user session in LON-CAPA without re-authentication.

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

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

Categories for configuration for each Consumer instance are as follows: 

\begin{itemize}

\item Required settings

\item Logout options
 
\item Mapping users

\item Roles which may create user accounts

\item New user accounts created for LTI users

\item LON-CAPA menu items (Course Coordinator can override)
 
\item Mapping courses

\item Mapping course roles

\item Creating courses
 
\item Roles which may self-enroll
 
\item Course options

\end{itemize}


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 domai
 n.

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:

\begin{itemize}

\item create a user account in LON-CAPA

\item create a LON-CAPA course or enroll in the LON-CAPA course associated with a specific course on the Consumer side

\end{itemize}

and will also determine what information source(s) may be used to populate user accounts for new user(s), what type(s) of LON-CAPA course may accommodate users in sessions launched via LTI, and lastly which of the following are available on the LON-CAPA side:

\begin{itemize}

\item should logout from the Consumer trigger a callback to perform a user logout from LON-CAPA?

\item which LON-CAPA menu and page header items should be available by default for user/course session(s) launched from the LTI Consumer?

\item should newly enrolling users be assigned to a section in the LON-CAPA course?

\item should a course roster be retrieved from the Consumer?

\item should grades be returned to the entry in the Consumer`s gradebook for the launch item?

\end{itemize}

In the case of menu items, page header, and inline menu display, the values set for a domain may be overridden by a Course Coordinator in a LON-CAPA course utilizing course session launch via Consumer, via the ``LTI provider settings'' item in the course.

If the LTI Provider functionality set for a particular Consumer accepts user identity information but not course identity information, then LON-CAPA's standard Roles/Courses page will normally be used to display roles in LON-CAPA which a user originally authenticated by an LTI Consumer may select.

The one exception is when the destination URL is a shortcut to a specific folder or resource in a specific course, i.e., the launch URL is: /adm/lti/tiny/domain/uniqueID. In that case, if the user has an unexpired role in the course to which the tiny URL belongs, then role selection will occur automatically, and the folder or resource will be the first item displayed after the user's session has been established, as long as the mapped course item (a resource or a folder) does not have a deeplink parameter in effect which requires launch from a different Consumer.

On the Consumer side, an instructor will typically select an External Tool item for LON-CAPA from a list of LTI-enabled tools available, as configured by an administrator who manages the Consumer system. If the Provider configuration in LON-CAPA for this Consumer accepts course information, then the destination course domain and courseID in LON-CAPA are determined in the following order:

\begin{enumerate}

\item from the value of an (optional) custom_coursedomain item in the payload sent by Consumer on launch.

\item from a course look-up if mapping from Consumer ``course'' and Provider ``course'' has been established previously, and stored (configurable).

\item from tail of requested URL (after /adm/lti/) if it has the format of a LON-CAPA resource identifier (known as a symb).

\item from tail of requested URL (after /adm/lti) if it has the format of a LON-CAPA course folder URL.

\item from tail of requested URL (after /adm/lti) if it has the format: /domain/courseID.

\item from tail of requested URL (after /adm/lti) if it has the format: /tiny/domain/uniqueID, i.e., a URL shortcut. 

\end{enumerate}

If the extracted LON-CAPA course domain and/or courseID do not exist then the request is invalid, and no user session will be established.

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