SPIKE How should the registration process work for LTI1.3

[marcospri]

This currently involves a open form that anybody can use. We could keep the process as it is for LTI1.1 apps but use any new method for LTI1.3 setups.

Independently of the solution we opt for, this is roughly the information that needs to be exchanged:

• We must provide the school with some configuration parameters. Unless we use for the last option on https://github.com/hypothesis/lms/issues/3688 this will be the same values for every school (ie this could be a kb article per LMS)

  If we use one JWK per school there would be an extra step of generating those and sending an unique URL to the school.

• The previous step will generate a client_id

• The tool then needs to be added to the account/course using that client_id. That will generate a deployment_id.

• The school needs to send hypothesis both client_id & deployment_id along with some auth related URLs (JWK endpoint, oidc endpoint, issuer name).

This could happen over email, using an open form, using a form behind a login, form using an unique token....

[marcospri]

Some other tool's install instructions:

• https://networkmanagerguide.pressbooks.com/chapter/configuring-the-lti-1-3-plugin/#canvas
• https://help.vocareum.com/en/articles/5085436-lti-1-3-setup-guide-for-canvas
• https://zoomappdocs.docs.stoplight.io/lti-pro-v2/guides/canvas/LTI-Pro-1-3-canvas/lti-1.3

[chrisshaw]

Here's another we generally look at, not that they're a good reference, just another one.

• https://support.piazza.com/support/solutions/articles/48001191921--lti-1-3-configure-piazza-with-canvas
  • https://support.piazza.com/support/solutions/articles/48001191922--lti-1-3-configure-piazza-with-moodle
  • https://support.piazza.com/support/solutions/articles/48001191926--lti-1-3-configure-piazza-with-d2l-brightspace

[chrisshaw]

We decided to gate this. We will, however, likely need to provide a way for customers to provide their Canvas API keys to us somehow.

We could still just have support send the keys and then shrink the online form to just dev keys. Then again, we want to close down the 1.1 form anyway. So perhaps we develope a public facing solution, such as a one-time code or something.

[marcospri]

A rough flow of how registrations could work could be:

• All the information the LMS needs from us can be in a KB article. No need to generate keys or anything.

• Once they follow the KB article instructions they need to send us:

  • client_id
  • deployment_id
  • key_set_url
  • auth_login_url

And, if we wanted to support a manual path to link old/new installs we could ask the consumer_key they are replacing/updating.

[chrisshaw]

:+1: Cool. Question, once they've created a deployment ID, the fact that they need to send us these values means we can gate their true registration, even if the form is public.

In these LMS-specific form, we can ask for the Canvas Dev keys, which features to enable for Blackboard REST API, etc...

@marcospri In absence of a true admin portal at this time, I am going to suggest we make this a public form. Before we go farther in any direction, we may get away with just obscuring the docs and sending direct links to new customers, and then generating new instances if we don't think there's enough volume and we hide the help docs. It seems like this a solved problem that may not be worth complicating.

Alternative ways that complicate it slightly

We can instruct users where to post their information, and in doing so tell them that they need to have paperwork before we will enable their deployment. So the workflow behind the scenes would be: - Get a new form submission in - Check that the submission comes from an institution with paperwork - "Approve" the submission - Create a new app instance So ultimately I think this puts a manual approval process in front of whatever we do to drop stuff into app_instances, per https://github.com/hypothesis/lms/issues/3689 Alternatively, we could do public form + unique token ("subscription code") that we generate upon the signing of a deal if we think the manual approval is actually harder. I prefer this solution, but I think it will force us to start storing `organization_ids` as part of this project.

What do you think?

[marcospri]

For me the main difference between the public and private options is that in the private one we can treat as a an "admin pages" which relaxes a bit the UI requirements (as in, I can do it myself)

If we do it in a public form we might be in fact building the "admin portal" first steps. We might then required FE capacity for that.

It's true that the current public form is not up to the same standards as the the rest of the app so we could potentially do the new one like the LMS admin pages but without the login block.

Storing a boolean for approved/active in application_instance and filtering that for manual approval wouldn't be a big deal. I think the "unique token" might be a bit more complex and confusing to start with.

We decided not to that on day one but we also have to think about the update path for existing application_instannces. In my opinion we could start re-using the existing ones but adding the LTI1.3. That way we don't have to aggregate anything and we could use the existing API keys for canvas/blackboard.

[chrisshaw]

I see your point. For some reason I thought the current /welcome page was Hubspot generated.

I do think we can go for a manual migration path--may not for cert or even for launch, but soon after. If we're asking for sensitive info (consumer keys for migration, Canvas dev keys for new installs), wouldn't we need to have something user-facing? In which case it has to be some UI? We couldn't be sending those over email. I'm imagining for UI work, copying the current /welcome form and changing the fields.

Frankly, maybe that UI could be generated by Hubspot. (I believe this is how the support forms work in the knowledge base.) Then we let support enter that into an actual support admin page (or trigger an automated workflow). If push comes to shove, I'd bet we could use an off-the-shelf app to handle the UI to start with. Budibase comes to mind.

[marcospri]

When no API keys are involved

This could 100% done in some admin page. We'd need:

• issuer
• client_id
• deployment_id

For new registration (issuer + client_id combinations) we'd also need:

• auth_login_url
• key_set_url
• token_url

For existing registrations the admin pages should auto-fill these.

When API keys/secrets are involved.

We need a way to store these in the DB.

• Same admin page + emails/phonecalls?
• Some public URL based on a token with a form to fill them up?
• ???

When upgrading an existing install.

Depends on https://github.com/hypothesis/lms/issues/3691. It could be similar to the process adding a new one but adding an optional "consumer_key" field to that form to indicate upgrade vs new install.

[chrisshaw]

Is LMS Admin form viable?

Yes, for new customers and early adopters.

After meeting with Michael and Matt, the general consensus is that the LMS admin page are good for a first launch provided we limit installations to new customers. They're concerned they'll be on the hook for 250 migrations in a short matter of time. We will strongly recommend current customers hold off for a few weeks until we roll out a migration path. (If a current customer, even after strong recommendation not to, reaches out to migrate and make a clean break from their old data, we'll do it.)

Dev keys

@mattdricker and @mkdir-washington-edu will handle the credentials passover either over encrypted Zoom chat or through a third party tool designed for this sort of thing.

Migration

We won't go hunting for migrations. With that in mind, we can simply add the consumer key field to the LMS admin form and handle migrations on the same support call. I don't expect this to be a wave, really, because only a few schools are proactively demanding LTIA.

@marcospri It also strikes me that we could launch without migration via form, then add it in later and retroactively connect these schools manually. Would that work?

[marcospri]

We have now a viable registration process.

There's potential for improvements and alternative methods (dynamic registration, self-serve...) but I reckon they are out of scope of this first implementation.