Thoughts about migrating from OAuth applications to Integrations


#1

If you choose to make the switch from an OAuth application to an Integration, we want to help make the migration process as seamless as is securely possible. Since we’ll continue to support OAuth, the timeline around migrating once Integrations enters full production release will be at your discretion.

We’d love to hear your thoughts on what would make the best migration experience for users.


#2

Awesome @jmilas! We have added Github Integrations to Codecov and we have a couple customers beta testing it now. Overall it’s been a success :smile: :tada:

Here is some feedback:

  1. It’s fantastic that we no longer need “bot” accounts, this is our #1 support topic at Codecov
  2. There are occasional errors from integration authorized api requests. I presume they are due to the beta nature. We have had a couple 404/401 requests on the first api request after creating an integrations access token. The subsequent api requests return 200. Have you heard of this before?
  3. Worker tasks is an obvious use case for GitHub Integrations (GHI). I have a question about Web requests: when users login and Codecov receives an oauth-token for this user we would like to not require "repo" scope and use GHI’s on-behalf-of api strategy to assert permission to the project the user is requestioned. Is this a proper use case? Illustrated here

Thank you for your time!


#3

Hi @stevepeak, thanks for your feedback!

We can look more into the occasional errors part in that thread.

For the workflow question, we have more to flesh out in the coming weeks on the login from scratch side, but the new flow for authenticating as the installation, on behalf of a user, could replace requesting an OAuth token and using OAuth scopes for that access.

The example you shared wouldn’t suit, as currently GET /repos/:owner/:repo doesn’t support access by an installation on behalf of a user. Only these specified endpoints support that usage. Your installation could fetch that data, but that data might not be safe to show a given user.

Instead, a flow using the new Integrations could be something like:

  1. Obtain the user identity, confirming that user can view the given installation (https://developer.github.com/early-access/integrations/identifying-users/)
  2. List repositories available to that installation AND the given user (https://developer.github.com/v3/integrations/installations/#list-repositories)

Hope that helps.


#4

could replace requesting an OAuth token and using OAuth scopes for that access.

The idea here would be to start users at public scope and use integration access tokens, on behalf of a user, to access private repositories. All endpoints, such as contents for example, would be accessible through this protocol.

This would heavily improve customer adoption of Codecov as some users do not join simply because they cannot grant private scope to all repos.


As for the topic of occasional errors. See Random 401 API results

Thank you!


#5

As an org owner who just had another owner migrate us to the Integration version of a service, here are some bumps I hit in the workflow:

  • It appears to be hard (or impossible) to get a list of all the repositories using a given service
    • each of the 3 connection types (webhook, OAUTH, Integration) can have a different endpoint
    • there appears to be no API choice but to iterate over all methods in all repos to build a list of connections.
  • If the vendor chooses to disable OAUTH connections once a single Integration is installed, there is apparently no way to identify repositories which just had the OAUTH service cancelled.
    • there are no audit log events for this action that I could find
    • I’ve fallen back to having to poll all repos to build an offsite database to be able to ask “after the fact” if OAUTH was enabled.

GitHub folks:

  • It would be really nice if there was more of an audit log trail for actions related to Integrations.
  • It would be nice if there were some sort of “vendor ID” that was constant between OAUTH and Integration offerings. Or some way to tie the 2 accesses together.

Integration Providers:

  • If you don’t need to disable OAUTH when adding Integrations, that would save some coordination for owners in large organizations.
  • If you do need to disable, somehow providing a list/email/gist of “before” would be handy.

#6

With the current changes what is the mechanism an integration uses to identify the user installing the integration. As a third party integration developer, how can a user configure say a build pipeline, and ensure that the user configuring the integration has access to the repos being used? Do we need to fall back to OAuth for that?


#7

Hi @SajayAntony, there isn’t currently a safe way to surface that data to a user within an Integration, but we’ll have a new mechanism for enabling that kinda of functionality within a few weeks. Thanks!


#8

My main concern about migrating is figuring out a streamlined way to do it that doesn’t require user interaction - once a user “signs up” for our app and authorizes it, it’s hard to get them to come back and do another step - I’m worried they’d be more likely to just disable our app instead of going to the trouble to set it up all over again.

One suggestion I’d offer, if it does require their ok: could there be a way to “ask” for a user to do such a thing, (maybe requiring the integration/oauth permissions “match up”), and have it notify them in GitHub, so it’s easy for them to do with a single button click?


#9

Background

Our OAuth application creates builds from users’ source code. It works like this:

  • We require the repo scope from users when they login.
  • Our webpage has an interface that lets users select which repos we should build.
  • When a user selects a repo, we create a webhook in the repo. We also store in our database which user has enabled this repo.

Migrating problem

As mentioned above, we keep track of the repos that each user has enabled (and the associated webhooks). Therefore, ideally, when a user updates his account from OAuth apps to Integrations (GitHub apps), I want to disable all previously-created webhooks and install the integration in those repos.

However, it is not possible to automatically install the app into repos. I understand that this is the whole point about GitHub Apps – the user, not the app, selects which repos to install. Nevertheless, it could smoothen the migration flow for users (and allow us to completely sunset OAuth app support eventually) if we could let the user convert OAuth-enabled repos into Integration-enabled repos. One way to implement this is to have the app tell GitHub what repos the user has previously enabled, and GitHub asks the user to confirm.

The suggestion

To be generic, apart from the github.com/apps/:app_slug/installations/new interface, it would be great to have an additional repo setup flow through predefined “installation batch” and let the user confirm. For example:

  1. App -> GitHub: Create an “installation batch”
POST /app/installation_batch
Authorization: ${INTEGRATION_JWT}
Content-Type: application/json

[
    72737686, // repo ID for SOF3/simple-plugins
    40283954, // repo ID for SOF3/Basin
    76901140, // repo ID for pmmp/PocketMine-DevTools,
              // where pmmp is an organization that SOF3 owns
}

The server can respond with an installation batch ID:

201 Created
Content-Type: text/plain

d3adb33fc0defac3
  1. The app redirects the user to GitHub to migrate:
https://github.com/apps/:app_slug/installations/batch?batch_id=d3adb33fc0defac3
  1. GitHub will display an interface like this:

{APP_OWNER} wants to install {APP_NAME} in the following repos:

  • SOF3
    • simple-plugins
    • Basin
  • pmmp
    • PocketMine-DevTools

Confirm

  1. After the user clicks “Confirm”, the user is redirected to the app’s setup callback URL, and the installations are created as required by the batch.

#10

So…

Why not just github.com/apps/:app_slug/installations/new?repos=72737686,40283954,76901140 ?