Busy couple of weeks here. I’ve personally been sick, hence the lack of a ChangeLog last week. Sorry about that!

We’ve made a lot of great progress on getting Review Board 4.0 ready for beta, and updating the ecosystem of packages (such as Power Pack and Review Bot), but there is one urgent thing that came up that’s taking a bit of our time.

GitHub’s Authorization Changes

For many, many years, GitHub’s API has offered several options for authenticating with the API. Our initial integration with GitHub was written 10 years ago, and while it’s evolved over time, it’s continued to use the same original authentication methods to communicate with the API and link accounts.

In November, GitHub announced their were deprecating those methods. Frankly, due to its proximity to the holidays and some time-consuming work on our plate, this announcement slipped by us.

There are really two main ways in which this affects us:

1. HTTP requests to the API need to change how they pass API access tokens
2. We can no longer automatically exchange user credentials for an API access token when linking an account for a repository

GitHub API Authentication

GitHub’s APIs have historically taken an ?access_token=... parameter in API requests, and the original code we wrote to talk to the API continues to use this method. (If it ain’t broke…)

The modern approach is to make use of the HTTP Authorization header to pass in the access token. This is more standards-compliant and probably simplifies a lot of URL building and logging on their end.

This week, they began e-mailing users whose accounts were accessing the API using ?access_token=. You may have seen these, if you linked your GitHub account to Review Board. It’s annoying, but it’s designed to be, so that people update their software in time.

We’ve fixed this internally, and are testing to make sure it works everywhere. We’ll have a build out soon (see our timeline toward the bottom of this ChangeLog).

Linking GitHub Accounts

In order to talk to a source code repository, we typically need credentials of some kind. This may be a username and password, an API key/authentication token, or an SSH key.

Traditionally, we’ve been able to get by with taking the credentials right on the repository configuration page, combining the steps of linking an account and creating a repository. This is just easier for many reasons, and worked great with GitHub.

The GitHub process went like this:

1. We’d provide fields for a username and password to a GitHub account to use for repository access (though we’d never store the password).
2. When saving the repository, we’d use those credentials server-side to immediately make a request to GitHub’s Authorizations API to request a new access token.
3. We’d store that token and use it for all future API access.

This token was associated with the user’s account, and could be revoked at any point. We never had to store the password, like we unfortunately must do with some services that lack any form of authentication token capability.

This had always worked before, but it will be changing going forward, as the Authorizations APIs we used is now deprecated.

Short-term, we’ll be changing the dialog to provide instructions on how to generate a personal access token, and a field for providing it (instead of a password). This is an annoying extra step for users, but it’s a working solution we can employ short-term (and we already use this approach for some other services).

Long-term, we need to modernize the configuration experience, taking full advantage of OAuth web flows for linking accounts.

Challenges of OAuth in Review Board

First, let’s quickly go over OAuth (or, more specifically, OAuth2, the modern version of the standard).

OAuth is a standard way for a service (Service A) to request access to another service (Service B), on behalf of a user. You’ve probably seen basically this before when you’ve initiated a “Log In With Facebook” or when you’ve connected some service to Slack. You click a button, a browser window pops up and presents a page on Service B telling you that Service A wants access via your account, telling you what permissions it requests.

While complicated, it’s a pretty great thing to have in the modern world, but it’s not automatic.

Before Service A can even begin this process, someone must register it on Service B (through whatever mechanism is required by that service — this usually requires filling out a form). The result is a Client ID and a Client Secret, which must be stored somewhere and then used when initiating the OAuth process.

The Burden on Administrators

It’s very important that the Client ID and Secret are kept secure and not shared, and this is where things get more difficult for tools like Review Board.

Review Board is open source and self-installed, so we can’t supply a Client ID or Secret as part of the installation. That means an administrator must perform this task, and this can be a real annoyance when just getting started. It’s worse for some services than others.

Fortunately, it only has to be done once per required service, but we try to avoid this extra step when there are alternatives. We do take care of it on RBCommons so users don’t have to, at least.

In the case of GitHub, they’ve thought through this and have some mechanisms (such as App Manifests) we’re looking into that should aid in OAuth registration, but we haven’t yet figured out how this is going to work in the end.

Timeline: When Is This All Happening?

There’s no public information yet on when GitHub will be removing the old APIs, though we’ve been in communication with them and have a timeline we’re comfortable with. They’re still fairly early in the deprecation process, and have a history of handling deprecations very well.

We have three phases:

1. Update the API authentication method

   Our plan is to release Review Board 3.0.17 early next week (targeting February 11th, 2020) with this fix.

   We are not planning (at this time) to backport this to older generations of Review Board.

2. Request Personal Access Tokens when linking accounts

   This is the manual version of what we’ve been doing behind the scenes. Users will need to generate their own token and supply it when linking an account.

   We are planning to provide this a couple months before the API removal date. This is to keep the process nice and simple as long as possible, but to allow time for people to upgrade.

3. Implement an OAuth web-based account linking workflow

   This will likely come sometime after the API removal, and will be in Review Board 4.0. We’ve been planning this anyway, and it’s not (at this time) needed to remain compatible with GitHub. Though it is the better method.

These plans may change as we go. We might decide to fast-track the OAuth web-based flow, for instance, based on other factors.

We still really want to get Review Board 4.0 wrapped up soon, and a lot of “urgent” things like this have come up, causing further delays, so we’re punting what we can for now.

More on that soon.

Whew.

That was a lot to talk about.

If you want to know more, have any questions, or are curious about anything else, please reach out on our community forum.

We’re also on Reddit (/r/reviewboard), Twitter, Facebook, and YouTube if you want other ways to keep up with Review Board and Beanbag.

Read More