Migrate GitHub Classroom to a GitHub App

[d12]

To date, GitHub Classroom has been an OAuth app. GitHub apps are the way forward and have more features. They also allow us to be more granular in the permissions we request from our users.

This will also allow us to rework our on-boarding experience. One of the biggest pain points teachers face is having to go to the OAuth installation page and click "grant" when they make a new org. There aren't any instructions saying what to do on this page, and there's no redirects back to Classroom after they grant access to the org. Teachers often get lost here and start to get confused between GitHub and GitHub Classroom.

We can skip this whole step as a GitHub App. We will still need to perform an installation per org, but we can send them directly to the installation page which will have clear instructions saying what to do, and after clicking the big green button, they get automatically forwarded back to Classroom.

tldr; As a GitHub App, we get access to the newest GitHub API features + we skip the confusing OAuth org grant flow. Lets do it :+1:

cc @tarebyte, a lot of this is paraphrasing from conversations with you. Let me know if I got anything wrong here :)

cc @andrewbredow cc @mozzadrella

[spinecone]

Making a note here that moving to a GitHub App would also allow us to use an installation token for rate limiting rather than our current strategy of picking a random org member's token, which would give us a higher rate limit overall and behave more consistently.

[spinecone]

Next steps for migrating to a github app:

• researching github apps and their tokens
  • what can they access, maybe even private repos owned by users?
  • how long do teacher tokens last? what happens when a token expires?
  • we need an app that has "unlimited" access to github.com
  • team sync uses github apps (mtodd?)
  • github pages uses github apps, migrated from oauth apps (ben emdon?)
  • how complex is it to migrate to github apps?
  • continue talking to tarebyte
• decide how to communicate these changes to users (some kind of warning message in advance of changes)
• migration for old data
• way of handling future private starter code repos
• how much do people use old assignments? (creating new repositories on them)
• needs to be rolled out between semesters (december or later)

[spinecone]

I did some preliminary research on how we might migrate to a GitHub App. Some notes:

• We would need to continue using OAuth to handle user login
• The GitHub App for classroom would need to be installed on each organization used to set up a classroom
• The backend process for authenticating a request with a GitHub app would be:
  • Create a JWT token for the app itself (has a 10 minute expiration)
  • Use the app's JWT token to generate a token for the app installation (1 hour expiration)
  • Use the installation token to make API requests on github.com
• Since tokens expire so quickly it's recommended that we use redis to store them rather than a more persistent storage, and set them to expire in redis before the actual token expires so we don't attempt to use an expired token (there is prior art in other projects in the github org for this process ✨ )
• Since we are planning to allow users with org permissions other than admin to use classroom in the foreseeable future (https://github.com/education/classroom/issues/765) we should use a combination of user-to-server and server-to-server requests. We would use a user-to-server request to determine what the current user has access to (for example a repo to use as a starter code repo as an assignment), and a server-to-server request to create the student repositories for that assignment.
• It may be useful to rethink some of our user experience around onboarding/creating classrooms and assignments in parallel with these changes. For example, directing users to install the app on an organization during the user signup process, and setting the expectation that most users will only ever need to use one organization within classroom

Useful resources have been https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/ and advice from @mtodd ✨

[d12]

This research is really valuable, thank you @spinecone! cc @femmebot as there may be design implications in the way we move forward here.

A next step could be putting together a plan for token management in a GitHub App world, since it looks like we're managing more than 1 type of token now (and we have to do some intermediate token generation type stuff). After that, giving a go at a spike would be valuable.

[femmebot]

• One of the things I was trying to figure out was whether we could get more granular info regarding orgs and access so we can, in turn, offer the best path forward. (Related question: if we can get these details, would we be able to compile analytics for what our conversion rates look like given what type of org access they have?)
• And, if they didn't have an org (or wanted to create a new one), could we direct them to a custom org creation path?
• Once they're done with the app installation (assuming it's taking place on dotcom), can we automatically redirect them to Classroom?

[spinecone]

Couple more notes:

• We can request a user's org memberships through the github.com API and link directly to the installation page for an org through the url https://github.com/apps/[app name]/installations/new/permissions?target_id=[org id]
• If the user has admin access to an org, the installation page looks like this:
• If the user doesn't have admin access to an org, the installation page is for requesting rather than granting access and looks like this: