Copyright (C) 2018-2022 The Open Library Foundation
This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.
The purpose of this edge module is to connect LMS such as Sakai and Blackboard (LTI Platforms) to Folio via the LTI Advantage protocol for the purposes of sharing the course reserves stored in Folio.
To accomplish this, this module acts as an LTI Tool Provider. It adheres to two parts of the LTI Advantage spec to accomplish this. First, security is enabled via a third-party-initiated OIDC Authentication flow (this is a generic ). Second, the actual course reserves are requested and shown via messages using the Resource Link spec.
The general use flow is as follows:
- Upon navigation to the tool's page on an LMS such as Sakai (the LTI platform), the platform sends an OIDC login initiation request to the tool at a predefined URL.
- This request is handled in
LtiCoursesHandler::handleOidcLoginInit. The request is parsed and validated.
- If the request is valid, it responds with an HTTP 302 Redirect to a preconfigured URL for that platform.
- The platform handles that redirect and bounces a request back to the tool to the tool launch endpoint with the LTI request itself.
- The tool parses the LTI request which contains info about which course is being viewed in the LMS. Based on that, it fetches the course and its reserves from mod-courses, renders them in HTML, and sends back the HTML.
- The platform takes the response and displays it in an iframe.
Configuration is done in two ways: system properties/args/secure stores, and LTI Platform configuration.
Arguments / System Properties
Values common to Folio Edge modules are configured using the methods made available in edge-common. These handle things like the
secure_store_props. E.g., you can run the module as
java -jar edge-lti-courses-fat.jar -Dokapi_url=https://okapi.folio.my-university.com .... Besides the common values defined in
edge-common, this module also uses the following system properties.
||File path to a PEM file containing an RSA-encoded (PKCS8) private key. The key will be used by the Edge module when signing responses. This is needed if your LTI platform creates a private key for each tool. This edge module will generate its own keys if this property is not defined.|
||File path to a PEM file containing an RSA-encoded (X509) private key. The key will be used by the Edge module when signing responses. This is needed if your LTI platform creates a private key for each tool. This edge module will generate its own keys if this property is not defined.|
||TTL in ms of the OIDC
||Never use this in production!!! This allows you to debug requests by sending requests to the
||A box.com API App Token that allows the edge module to rewrite links to Box.com files (eg, https://my-uni.box.com/file/12345678) to an URL that is handled by the edge module (eg,
||TTL in ms of the download URLs generated by the edge module when rewriting Box.com links||600000|
LTI Advantage requires that Platforms and Tools have knowledge of one other before they can safely and effectively communicate. This Tool is configured with the platforms it should respond to via the
ui-lti-courses module. More information about what is configurable can be found there, but at a minimum, this Tool needs to know the following about a platform:
- Client ID: The ID that was generated for the Tool by the Platform.
- Issuer: Corresponds to the
issfield in a JWT sent by the Platform.
- JWKS URL: A location where the Tool can fetch the Platform's JWKS so that it can decode the JWTs sent and signed by the Platform.
- OIDC Authorization URL: The URL that the Tool should redirect the Platform to after handling an OIDC Login Initiation.
- Search URL: A templated URL that the Tool will use when rendering HTML links to the course reserve items.
A full Code Tour that's intended for a technical audience is available here.
edge-common contains a description of the security model as it relates to the
apiKey. Additionally, further security is added due to LTI's use of an OIDC login flow.
This module requires passing the
apiKey as a path param, e.g.,
https://my-server.edu/lti-courses/launches/myApiKey. The reason for this is that many LMS expect to have exclusive use of the query params and insert a second
? in the URL, so this just ensures things are a bit less flaky.
Platform RSA Keys
The Platform's public key is fetched via a JWKS. The Platform's JWKS URL is configured using the
Institutional users should be granted the following permission in order to use this edge module:
Box.com API integration
Folio inventory items can have their "Electronic access" defined with an URL. If an item's electronic access URL is a link to a file stored on box.com (eg, https://my-uni.box.com/file/12345678), the link rendered by the edge module would normally link the user to that same box.com URL. If the user viewing the link doesn't have permissions to view the page, then the edge module can be configured so that the link rendered can instead result in the user downloading the file directly regardless of their permissions.
To enable this functionality, you need to pass in a Box.com API App Token via the
box_api_app_token system property as described above. Afterwards, when responding to a LTI Request the edge module will rewrite box.com links into generated links to itself that contain a hash of the file ID. The generated link will be valid for 10 minutes by default. When a user clicks the link, the edge module will download the file directly using it's box.com App Token and route the file contents to the user as a file download.
- OAuth 2.0 and OIDC (in plain English): I love this video as a primer on the oft-confusing OAuth/OIDC flow.
- Adding the reference implementation Tool to Sakai: This is useful if you need something to pattern adding this Tool into your instance of Sakai (or other LMS).
- LTI Advantage Reference Implementations: Useful for debugging platform/tool issues.
- ui-lti-courses: Folio settings module that allows you to register LTI Platforms for this tool