Change Canvas Studio admin token refresh to work more like other refreshes

[robertknight]

Canvas Studio admin token refreshes used to be done transparently by the backend when needed, which is different than how this is handled for other APIs. We need to introduce a mechanism to prevent concurrent refreshes of access tokens, and this will be easier to do if all token refreshes work the same way. Hence this commit changes Canvas Studio APIs to fail with an error if an admin refresh token is needed, and the frontend will initiate a refresh.

Unlike other token refreshes, if it fails, we show a custom error dialog to the user which doesn't prompt them to re-authorize (they can't, the current user is not the admin) and instead shows more specific instructions.

This change only applies if the current user is not an admin, otherwise refreshes are handled exactly as with other APIs, including providing the option to re-authorize if the request fails.

There is nothing in place currently to prevent multiple concurrent calls to the admin token refresh endpoint. This will be addressed in future changes.

---

Testing:

1. Launch a Canvas Studio assignment (eg. https://hypothesis.instructure.com/courses/125/assignments/6473). It should refresh if needed. For testing purposes, you can expire existing tokens in the LMS DB using UPDATE oauth2_token SET access_token = 'foo' WHERE service = 'canvas_studio'.
2. Invalidate the current access token, then force the refresh to fail using:

diff --git a/lms/services/canvas_studio.py b/lms/services/canvas_studio.py
index 9c76dd152..ff05b2172 100644
--- a/lms/services/canvas_studio.py
+++ b/lms/services/canvas_studio.py
@@ -158,6 +158,8 @@ class CanvasStudioService:
         """Refresh the existing admin access token for Canvas Studio API calls."""
 
         try:
+            # TESTING
+            raise ExternalRequestError(message="Oh no!")
             self._admin_oauth_http.refresh_access_token(
                 self._token_url(),
                 self.redirect_uri(),

This should result in an error dialog like:

[seanh]

Code looks fine and works for me 👍

I think the error messages need to be more specific. The last thing we want is for the feature to stop working for the whole school and to brick-wall users with an overly-generic error message that doesn't give them the information they need to fix the problem.

"Your Canvas LMS administrator needs to re-authorize the integration between Hypothesis and Canvas Studio." Which administrator? It needs to be the particular one whose email address we have (although as discussed on Slack, perhaps we should change that). Re-authorize Hypothesis how? (They need to launch an assignment.)

[seanh]

You might be able to avoid the doubling up of refresh endpoints and views by using a ?admin query param.

[seanh]

I'd recommend a more detailed error message than this.

• What exactly does the admin need to do in order to re-authorize the integration? Go into a course and launch an assignment? Whatever it is, it should be in the error message.
• Who exactly needs to do this? It's not just any admin, it has to be one particular admin whose email address we have
• I'd also make "Your Canvas LMS" clearer and more specific by including the URL of the LMS instance: "The hypothesis.instructure.com administrator [email protected] needs to..." (and avoid using the jargon term "LMS" which users may not understand).

These error messages are going to be screen-shotted or copy-pasted by students and sent to their instructors, or sent by instructors to their admins, or to us. The more detailed and specific the error message can be about exactly who needs to do exactly what, the better chance the users have of recovering quickly without a lot of time lost to confusion or back-and-forth with Hypothesis support.

[robertknight]

I filed #6302 to track making the error message more specific.