Return to Course_Prefs_Linkprotection.tex CVS log

Up to [LON-CAPA] / loncom / html / adm / help / tex

Annotation of loncom/html/adm/help/tex/Course_Prefs_Linkprotection.tex, revision 1.4

1.1       raeburn     1: \label{Course_Prefs_Linkprotection}
                      2: 
                      3: 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
                      4: 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
                      5: an online proctoring environment which students must use when accessing an exam folder in a LON-CAPA course.
                      6: 
                      7: Although configuration primarily uses the deeplink parameter available via the Parameter Manager for a specific resource or enclosing map/folder,
                      8: 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:
                      9: Settings $>$ Course Settings $>$ Display (``Link protection'' checked).
                     10: 
                     11: 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 
                     12: ``Link protection'' box for the deeplink parameter itself, available when editing the deeplink parameter, if the currently checked radio button is: 
                     13: ``course LTI launch''.
                     14: 
                     15: For each LTI launcher configured in a LON-CAPA course, the following need to be specified:
                     16: \begin{itemize}
                     17: \item Launcher Name
                     18: \item LTI Version
                     19: \item Nonce lifetime (s)
                     20: \item Key
                     21: \item Secret
                     22: \end{itemize}
                     23: 
                     24: 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.
                     25: 
                     26: The \textbf{LTI Version} will be 1.1. It is expected that newer versions will also be supported in the future.
                     27: 
                     28: 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.
                     29: 
1.2       raeburn    30: 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. 
1.1       raeburn    31: 
                     32: 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
                     33: displayed when setting the deeplink parameter when the currently checked radio button is: ``domain LTI launch''.
                     34: 
                     35: 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
                     36: 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 
                     37: 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.
                     38: 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''
                     39: 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
                     40: the request to the LON-CAPA endpoint URL.
                     41: 
1.2       raeburn    42: 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:
                     43: 
                     44: \begin{itemize}
                     45: \item Source of username in LTI request
                     46: \item Action if username does not match enrolled student
                     47: \end{itemize}
                     48: 
1.3       raeburn    49: 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.
1.2       raeburn    50: 
                     51: 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?'.
                     52: 
                     53: 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. 
                     54: 
                     55: 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. 
                     56: 
                     57: 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.
1.1       raeburn    58: 
                     59: 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, 
                     60: 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.
                     61: 
1.4     ! raeburn    62: Following the hostname, the remainder of the URL will have the format:
        !            63: 
        !            64: \begin{verbatim}
        !            65: /adm/launch/tiny/$domain/uniqueID
        !            66: \end{verbatim}
        !            67: 
        !            68: where /tiny/\$domain/uniqueID is a shortened URL, unique to the particular folder or resource in the specific course.
1.1       raeburn    69: 
                     70: Course Coordinators can generate shortened URLs for items in a course by using: 
                     71: Course Editor $>$ Content Utilities $>$ ``Display/Set Shortened URLs for Deep-linking''; see: Short URLs section \ref{Docs_Short_URLs} 
                     72: