Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Canvas users have to manually create and activate Hypothesis accounts #342

seanh opened this Issue Jul 17, 2017 · 1 comment


None yet
4 participants
Copy link

seanh commented Jul 17, 2017

See also


Currently users of the Canvas app need to create their own Hypothesis accounts manually. This means manually creating a unique username, giving an email address, manually creating and remembering a password, and verifying the given email address by clicking on a link that we email to it. You can't login to your Hypothesis account until you've verified your email address. Sometimes the verification emails don't arrive (or go into spam folders etc).

For classrooms using Canvas creating accounts can be particularly onerous as the teacher has to get every student through the account creation process successfully before they can begin a Hypothesis annotation assignment.

I also imagine there might be trouble identifying students, given that they can choose any Hypothesis username they want and this may not match their real name or Canvas username.

There are some other parts of the Canvas app that are awkward with usernames too (see the various Google docs and screencasts, TODO: list the particular problems here).


  • This issue is blocked by #340 and #339 - we can't implement improvements to the Canvas app until we've at least made significant progress on bringing the Canvas app up to production quality, and we can't deploy improvements to the Canvas app until we've migrated it onto our production infrastructure.

  • This issue also depends on Canvas users have to manually create and join Hypothesis groups #341 because it raises the question: I've been automatically logged in to Hypothesis using my Canvas account, what group(s) do I see in the sidebar?

    Assuming that the Hypothesis user accounts that we automatically create for Canvas users are third-party accounts rather than first-party accounts, that is they have their own Hypothesis authority (e.g. "canvas" rather than ""), then it's not possible for those accounts to see the normal Hypothesis Public and private groups (or to create new groups, view activity pages, etc).

    This issue and #341 will probably have to be developed behind the same feature flag, and both released together.

Possible ways around this dependency

We considered but rejected a few workarounds that would allow us to deliver Canvas account integration without also having to deliver #341 at the same time:

  • We considered allowing users to log in to a third-party Canvas account, but still see the normal first-party Public and private groups. This would be an intermediate step that allowed us to implement Canvas accounts without yet solving the problem of automatically-created Canvas groups. We rejected this because it would involve breaking down the "authority" divide in the h architecture - each account authority (Hypothesis, eLife, Canvas...) has its own completely separate set of user accounts and groups. Canvas users can't see Hypothesis groups. We probably actually don't want Canvas users to see Hypothesis groups in the long-term, and allowing Canvas users to see Hypothesis groups in the short-term isn't a good intermediate solution because it'd actually be a lot of work and would do damage to the h architecture.

  • We considered giving third-party Canvas accounts their own set of groups that behave the same as first-party groups - a Public Canvas group (you need a Public group to be the default one when the user isn't a member of any private groups) and manually created and joined Canvas private groups. Again this would be an intermediate step that'd allow us to deliver Canvas account creation without also automating Canvas group creation yet, and it would avoid having to break down the authority divide in the h architecture. But third-party accounts currently don't have access to web pages, including the pages for creating and joining private groups. Implementing that is probably enough work that it wouldn't be worth it as an intermediate step - we may as well just jump directly to automating Canvas group creation as described in #341.

  • We could avoid this dependency by creating first-party accounts for Canvas users, but that then raises its own issues, such as the potential for username conflicts with existing, manually created first-party accounts. See below.

First-party or third-party accounts?

Automatically creating and logging in to first-party accounts for Canvas users would mean that they could continue to have the Hypothesis experience they have now (the Public group, and ability to manually create and join private groups, and activity pages, etc) and then we could solve the problem of automatically creating private groups for Canvas courses later.

But auto-creating first-party accounts has a lot of issues. You can't have two different first-party accounts with the same username, or with the same email address, and someone might have already manually created an account with the same username and/or email address as the one we want to automatically create an account with. If an account already exists we don't know if it was created automatically by Canvas or manually by a user, and we don't know whether that user is really the same person who's currently using us via Canvas, etc.

Creating third-party accounts for Canvas users, as we do for eLife users, avoids this problem. You can have a third-party account with the same username and/or email address as an existing, manually created first-party account, that's not a problem. And we know that all Canvas third-party accounts were created automatically by the Canvas app. But third-party accounts lose access to the Public group, manual private groups, activity pages, etc etc. This seems to mean that we need to solve the #341 issue for Canvas users if we want to create third-party accounts for them.

Suggested solution

When the Hypothesis client is launched within Canvas:

  1. The Canvas app should generate a good Hypothesis username for the user.
  2. The Canvas app should create a new third-party user account for the Canvas user in Hypothesis, if one doesn't exist already (behind the scenes, no user interaction)
  3. The Canvas app should automatically (with no user interaction) log the user into their Hypothesis account, whenever they launch Hypothesis from within Canvas.


TODO: Insert explanation of authorities in Hypothesis.

  1. Generate a good Hypothesis username for the user.

    • Do we want this to be purely automatic? Or purely manual (we ask the user to enter a username and ask them to try again if it's invalid e.g. because it already exists)? Or a hybrid (generate a suggested username, give the user a chance to change it)?

    • What information can we get from Canvas about the user? That we can use to generate a good username for them. For example their Canvas username, their real name.

    • What do we want Canvas usernames to look like? The username needs to be unique within its Hypothesis authority, but can be the same as another username from another authority. The username should be human friendly, for example human readable and nice looking, because it's displayed in many places in the UI.

    • Should we generate display names for Canvas users as well? Depending on what we can get about the user from Canvas, we might want to generate a nice looking display name as well as a username. I'm not sure where display names are displayed and where usernames are displayed in Hypothesis currently.

    • Can we get an email address for the user as well? If we can get this from Canvas then we should probably add it to the account as well.

  2. Create a new third-party user account for the Canvas user in Hypothesis, if one doesn't exist already.

    There's already an API for creating new user accounts. The Canvas app will need an authclient in the h production database, and the Canvas app will need to hold on to this authclient's secret key, in order to use the create user API.

    What authority should the user be created under? For example one authority for all Canvas users (a single authority for the Canvas app)? Or maybe one authority per Canvas instance?

    If it's one authority for all Canvas users (across all Canvas instances) then we need to have some way of generating usernames that are globally unique across all Canvas instances.

    On the other hand if it's one authority for each Canvas instance, then the Canvas app needs to be able to create user accounts under many different authorities (with the third-party account support we have so far, for publishers, each publisher can only create accounts under one authority). For example we might need to create an authclient in the h db for each Canvas instance, creating a new authclient is currently a manual process and the Canvas app would have to hold the secret keys for all of these authclients.

    (Creating first-party user accounts, i.e. the "" authority, is also a possibility but it has its own problems and pretty different implications.)

    How can the Canvas app tell whether an account for this Canvas user already exists?

    If the algorithm that the Canvas app uses to generate a Hypothesis username is predictable (always generates the same username for the same Canvas user, even if that user might have changed some of their account settings in Canvas) then it can just see whether a user account with that username exists.

    Otherwise we may need to add an additional "third party ID" field to user accounts to allow the Canvas app to uniquely and robustly associate a Hypothesis account with a Canvas account, and an extra API may be needed for getting the Hypothesis user account with a given third party ID. Alternatively the Canvas app itself could maintain a mapping of Hypothesis user IDs to Canvas user IDs in its own database.

  3. Automatically log the user into their Hypothesis account, whenever they launch Hypothesis from within Canvas.

    This can probably be done by the Canvas app rendering a grant token into the document that's being annotated, the same as is done by eLife and the publisher test site.

Issues with the suggested solution

User who already have Hypothesis accounts won't be able to use them in Canvas anymore. They will still be able to use those accounts on the website and to annotate pages using the Chrome extension, but they won't be able to use to those accounts within Canvas.

There are existing users who've manually created normal, first-party Hypothesis accounts and have/are using them with Hypothesis inside Canvas. If, whenever Hypothesis is launched within Canvas, we automatically log the user in to an automatically generated third-party account based on their Canvas account, then the user will not be able to use any existing first-party Hypothesis account inside Canvas anymore. Just like you can't use Hypothesis accounts on eLife.

I don't think there's any easy way for us to allow existing accounts to be used or to link existing accounts to Canvas accounts. You can imagine ways that this might work but they'd involve user interaction and a lot more implementation work.

We do however already have a plan to allow a user to be logged in to multiple accounts at once in the future, this may solve this problem for us: #298.

Canvas users won't be able to view activity pages or other pages on the website including user pages, group pages, creating new private groups, joining existing private groups, the account settings page, the stream.

Various small changes will be needed to the client. Whenever you login with a third-party account the client currently does a handful of things that're only appropriate for publisher group / eLife accounts. We'd have to design and implement correct behaviours for each of these for Canvas. The difficult part of this is that we're going to want one set of behaviours for eLife / publisher groups, and another for Canvas (and another for first-party accounts), so the client no longer needs to just distinguish between first- and third-party accounts, it now needs to distinguish between publisher accounts and Canvas:

  • A few buttons and links send messages to the parent page, instead of doing their normal behaviour, when in third-party mode. This is so that, for example, when the user clicks the login button in the client it can trigger eLife's login process instead of our client's.

    • Login
    • Sign up
    • Profile page link
    • Help page link
    • Log out
    • These are all documented here
  • A few buttons and links are hidden when in third-party mode: the create new group button, the account settings link. (Actually, continuing to just hide these is probably the correct behaviour for Canvas third-party accounts as well.)

  • Usernames on annotation cards don't link to the users profile pages, when in third-party mode. Again, this is probably the correct behaviour for Canvas third-party accounts as well.

  • The moderation flag is shown when in third-party mode, even if the moderation feature flag is disabled. We probably don't want to enable moderation in Canvas.


This comment has been minimized.

Copy link

ajpeddakotla commented Apr 20, 2018

Closing this issue, but linking it for reference to newly created issues. #593 #594

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.