VitalSource supports OAuth-authenticated launches with limited LTI fields. The LTI fields that VitalSource requires before we allow book launches to work are:
- OAuth authentication:
- All book launches must have the parameters above. In addition to above, VitalSource sometimes requires these additional fields for more functionality, depending on the scenario:
Context (Course Information)
- These fields are appreciated to improve the user interface for the end-user:
Together, the fields above will allow VitalSource to understand securely who the user is, what kind of book license they should receive, and depending on the launch scenario, understand which Resource or Course information they should see.
The user_id is vitally important to VitalSource, since it determines the user identifier and keeps users separate and distinct in our system. All users at the institution must have a unique user_id and never share identifiers. If a user shares a user_id with another user, then those users will log into wrong Bookshelf accounts via the OAuth single-sign-on method that the institution is providing for them.
All users must have a LIS role defined for them. The common LIS roles are learner, instructor, and administrator. These roles are defined in the LTI standard, which leverages the Learning Information Services (LIS) standard. See More Information.
Bookshelf Online works best when launched into a New Window, instead of a frame or iframe. Please launch the user into a new window by defining launch_presentation_document_target=window.
For more information go to the IMS Global LTI implementation guide
OAuth is a security mechanism designed to protect POST and GET requests. This section only applies to protecting launch and other LTI messages that are being serialized and sent using POST.
The site oauth.net contains the specification for OAuth 1.0 and sample source code for implementing OAuth security. OAuth 1.0 specifies how to construct a base message string and then sign that string using the secret. The signature is then sent as part of the POST request and is validated by the [receiver] using OAuth.
Per the OAuth specification, the signing process produces a number of values that are to be added to the launch request:
oauth_consumer_key=b289378-f88d-2929-lmsng.school.edu oauth_signature_method=HMAC-SHA1 oauth_timestamp=1244834250 oauth_nonce=1244834250435893000
The important values for signing a message using OAuth are
the oauth_consumer_key and oauth_consumer_secret. The value of the oauth_consumer_key depends on which credentials are being used.
The oauth_consumer_key is passed in the message as plain text and identifies which TC is sending the message allowing the [receiver] to look up the appropriate secret for validation. The oauth_consumer_secret is used to sign the message.
[The sender and receiver] must support and use the HMAC-SHA1 signing method with OAuth fields coming from POST parameters.
Since we are using OAuth in a signing-only scenario (i.e., we are not using OAuth to transfer third-party identity), there is no need for an oauth_token as per OAuth 1.0 documentation section 6.2.3. Since most of the OAuth implementations in the marketplace have upgraded to OAuth 1.0A, Tool Consumers should include oauth_callback and set it to a value such as "about:blank". Note that Basic LTI's launch_presentation_return_url serves a very different purpose than OAuth's oauth_callback.
Upon receipt of the POST, the [receiver] will perform the OAuth validation utilizing the shared secret it has stored for the oauth_consumer_key. The timestamp should also be validated to be within a specific time interval. This time interval can be [receiver] defined, but should be small (on the order of a few minutes if you do not record nonces, or a few hours if you do).
The [receiver] should keep a record of nonces received and only allow the use of any nonce a single time. Combined with the timestamp, this means that they only have to keep track of nonces for a period of time equal to their acceptable time
interval. Recommended practice would be to have a time interval of 90 minutes so that you keep a record of nonces for 90 minutes.
NOTE that this security profile requires the [sender] and [receiver] to have synchronized clocks. The use of a configurable time interval can adjust for slightly-off clocks, but setting the interval too large is discouraged.
If the LMS manager would like to utilize either the Bookholder or the Course Carousel launch methods, then VitalSource will need to know the context of the launch. The context defines the course information so VitalSource can display the appropriate information and books to the user.
Context information will also allow VitalSource to report accurately and be able to distinguish between courses. Without the context information, VitalSource will see all launches as the same and without context, and therefore cannot provide any analytics about course activity.
The context_id is typically the LMS ID for the course. An example is “123456.”
The context_label is what VitalSource uses to map books to the course. An example is “SI182-sec1.”
The context_title is the title of the Course in a human-readable format. An example is “Design of Personal Environments.”
All context fields are appreciated, especially for reporting, but context_label is the only one that is required to support the Course Carousel launches.
If the LMS manager would like to utilize the Bookholder, then VitalSource will need to know the resource_link_id of the launch. This will allow VitalSource to recognize the particular launch from the LMS system and display the appropriate resource information to the user.
The Bookholder is a configurable launch that VitalSource allows the instructor to configure. When the launch is created, the Bookholder does not have an adopted book. A user with the Instructor role can then adopt a book using the Bookholder interface. Once a book is adopted, VitalSource will map the resource_link_id to the adopted book. Any users with a Learner role will then launch into the adopted book.
The lis_person_name_full allows VitalSource to display their name to the user. This provides a cleaner interface for the user. Otherwise, we will display the user_id to the user, which may not be as preferable.
The lis_person_contact_primary_email allows VitalSource to display the appropriate name to the user. This provides a cleaner interface for the user. Otherwise, we will display the auto-generated fake email address to the user, which may not be as preferable.
If the LMS manager would like to create launch links to books, or configure the LMS interface differently, we do allow a custom_vbid parameter to communicate the Vital Book Identifier to VitalSource. This identifier will tell VitalSource exactly which book to open. Alternatively, the VBID can be communicated as part of the Launch URL.
The LTI standard allows for non-standard fields to be communicated between parties. To do this, all non-standard fields must have the custom_ prefix. Custom parameters do not typically show with the custom_ prefix in the interface for configuration. For example, the LMS interface may show “VBID” as the configurable field instead of “Custom VBID.”
If the LMS manager would like to create deep-links to specific sections of a book, we allow the book location to be communicated in the LTI launch. Place the book location in the custom_book_location parameter, and the resulting book launch will use that location and land the user to that specified location.
The LTI standard allows for non-standard fields to be communicated between parties. To do this, all non-standard fields must have the custom_ prefix. Custom parameters do not typically show with the custom_ prefix in the interface for configuration. For example, the LMS interface may show “Book Location” as the configurable field instead of “Custom Book Location.”