Prove we can implement Vitalsource single sign-on

[jon-betts]

We want to streamline the user experience by introducing Vitalsource single sign-on, but we need to de-risk the technical aspects of the problem with a working prototype.

This prototype needs to:

• Prove each major element of the project (listed below)
• Demonstrate a working end-to-end process
• Get us into a state where we can develop this feature

It does not need:

• To resolve all UI issues to final quality
• Have tests
• Have production quality code

Tasks

• [x] Create a prototype which proves the point
  • https://github.com/hypothesis/lms/pull/4151
• [x] Create any devdata and instructions required to make this easy to work on
  • https://github.com/hypothesis/devdata/pull/60
  • https://github.com/hypothesis/flimflam/pull/1
  • https://github.com/hypothesis/lms/pull/4266
• [x] Write up the outcomes of the spike

Tickets

• https://github.com/hypothesis/lms/pull/4151
• https://github.com/hypothesis/lms/pull/4247 - Refactors
• https://github.com/hypothesis/lms/pull/4246 - Refactors
• https://github.com/hypothesis/lms/pull/4253 - Refactors
• https://github.com/hypothesis/lms/pull/4259 - Refactors
• https://github.com/hypothesis/lms/pull/4260 - Refactors
• https://github.com/hypothesis/devdata/pull/60 - Dev data

Questions we are trying to resolve

• Can we use existing Vitalsource APIs to automatically login users using the details we find in an LTI launch?
  • Generate an SSO link we can present in an iframe which results in the user logged into a book, at a specific location
  • Get a Vitalsource user from the LTI user
    • Required for the SSO link
  • Check that user has permissions on the given book id (SKUs / Vitalsource Book Id (VBID))
    • This is to work around failures in the existing SSO
• Can we setup a development env?
  • A hypothesis institution to represent customers
  • Can we get access to the Vitalsource LTI book reader app in one of our test LMSs (like Canvas)
  • This app can provision a user account or grant a book license automatically
  • Get credentials for the institution which will work with our test LMS installations
    • These allow you to make calls on behalf of users
    • List books that user can access etc
    • See: Vitalsource developer network
• How can we reset a given user to start from scratch?
  • Looks like we can't as Vitalsource control half the data
  • We end up "burning" users as a result
  • Can we do better? Simulate failures?

[jon-betts]

Notes

User accounts:

• Reference accounts
  • These have bare details
  • Like our shadow accounts LMS > h
• Full user accounts
  • The user has given email address + other details
  • Can login into Vitalsource themselves

[jon-betts]

Outcomes of the spike

Headline - it works

Not much to say, but it does work with some rough edges

The experience when a user doesn't have access to a book isn't great

The SSO redirect we use will detect the user doesn't have a license and block them. This is despite the fact that in many cases the user would be granted a license if they could make it to the book viewer.

At the moment we work around this by checking if they have a license first and then presenting an error page if they don't. This page contains a link to the viewer where they can fix it, but it doesn't log them in. We could put an SSO redirect link in the page, but it's one time use. Alternatively we could proxy the SSO link through our own API to provide a link that will repeatedly work to get the user logged in.

We should be using the customer API key

Pretty much what it says on the tin, but VitalSource have confirmed this is the correct thing to do, as it will

We probably want a bit more error handling

For the XML end-points it's much harder to apply a schema, which is a real pain. This means our error handling is more dodgy. We are also not inspecting the errors we get back for user credentials and we probably should be.

Perhaps we could address this as a part of: https://github.com/hypothesis/lms/issues/4219

Testing various failures is going to be a pain

It's not really possible to have all the different failure cases be easy to test without writing some fairly intense test harness.

We could stand up a fake version of the VS api locally or something, but it sounds like a lot of work.

[jon-betts]

I'm going to leave detailed instructions to the tickets that implement the features