Annotation of loncom/html/adm/help/tex/Course_Prefs_Linkprotection.tex, revision 1.2
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:
! 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.
! 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:
62: 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,
63: unique to the particular folder or resource in the specific course.
64:
65: Course Coordinators can generate shortened URLs for items in a course by using:
66: Course Editor $>$ Content Utilities $>$ ``Display/Set Shortened URLs for Deep-linking''; see: Short URLs section \ref{Docs_Short_URLs}
67:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>