Don't Be An OAuth Butt

James Carr / April 6, 2017

While these days I spend a majority of my time focused more on infrastructure engineering to scale Zapier, a lot of time during the early days was spent mixing engineering work with connecting new external APIs to our development platform. I always had a sweet spot for OAuth 2.0-based APIs because our platform makes it pretty easy to just register an app, plug the client ID and client secret in, add a few endpoints and boom… a new integration is ready for review and go live.

However, once in awhile I'd add an app that seemed normal until I got around to testing it to discover it's what I would call an OAuth Butt: the API uses OAuth 2.0, but with some non-standard deviations. I always hated it when we came across APIs like this because it meant a lot of extra work. Our early platform was geared towards OAuth 2.0 APIs, but once they deviated it made hard (or even impossible) to add. In fact, many of the changes we’ve made over the years have been to support OAuth Butts and other APIs with specialized approaches.

OAuth Butt Origins

I'll admit I'm not entirely original in coming up with the term OAuth Butt. I had actually first heard a similar term called Scrumbutt while attending an Agile conference earlier in my career. Scrum is an agile framework for any product or project development effort that was pretty popularly being picked up in the enterprise space at this time and the talk I attended
basically listed many anti-patterns that can lead to a failure of adopting Scrum.

In a nutshell, organizations falling into this trap would commonly describe their situation as "We're implementing Scrum, but with tweaks for our unique situation." Common examples included activities like having the daily standup report status to the scrum master rather than the team or having fixed release cycles vs. delivering in iterations. These anti-patterns would often be done with the best intentions but in the end would work against the organization and its efforts.

Likewise, I thought the term OAuth Butt was apt as it applied to a similar situation. Many organizations unveiled their API but discover a certain dilemma that makes them believe that they need to operate outside of OAuth 2.0's standard to accomplish their goals. If you find yourself describing your API and saying something like "We use OAuth 2.0, but with API keys," then you might be an OAuth Butt. Just like Scrummbutt, being an OAuth Butt works against your favor. It makes it harder to integrate with your API and as a result could hinder widespread adoption.

3 Common Signs of OAuth Butt APIs

OAuth 2.0 is almost five years old, yet we’re still seeing many different ways that it is implemented. I’ve compiled the three OAuth Butts I’ve noticed most often, and some ideas to keep yourself out of OAuth Butt territory.

I’m sure this list is not exhaustive. We invite you to add others you’ve seen in the comments!

1. Non-Standard Named Headers and Parameters

A very common issue that comes up are deviations of certain header names. One of our very successful integrations have an API that for unknown reasons calls the Bearer Authentication Scheme OAuth instead of Bearer.

For example:

     GET /resource HTTP/1.1
     Host: server.example.com
     Authorization: OAuth mF_9.B5f-4.1JqM

To successfully integrate this API, we had to write some custom extension points to our developer platform to hook in and change Bearer to OAuth during the authorization phase. Worse, some OAuth libraries may not be able to support it at all.

Similarly, we’ve noticed some APIs get creative naming refresh tokens, used for requesting new access tokens when the current one expires. While the specification is a little loose in this regard, the common convention has been to call the refresh token refresh_token when sent to the client. However, once in awhile this might be called something a little non-standard like id_token. That can throw integrators off, especially when they’ve successfully used many other OAuth APIs.

Solution: Always follow standards. And probably a good idea to follow common conventions, too.

2. Non-Standard Refresh Token Mechanism

One of the great features of refresh tokens is that they just work when utilized on Zapier. I could go look in our logs right now for 403 errors and see our engine running flawlessly, requesting new access tokens when the current access token expires and continuing the API request without stopping.

Thankfully the OAuth 2.0 standard is pretty clear on how these should work. A common violation can often be throwing an extra step somewhere in the process, a separate API call, or requiring a call to a separate location to refresh the token. Again, OAuth 2.0 should make it easier to integrate multiple APIs. When you’re requiring something unique, you’re making it harder.

Solution: Try using a common OAuth 2.0 library for your favorite language with your API. If you follow standards, this library should just work.

3. OAuth With Custom Data Sent Over

A request for help that can commonly come up on our developer platform support channel is the desire to send additional details as part of the OAuth request to do something like authenticate with a very specific scope on a resource that doesn't fit neatly into OAuth scopes. This typically turns into a "chicken or the egg" conundrum, as one needs to be able to authenticate against the API to get a listing of the resources (and hence, why they wrote into support).

The common solution here is to push the resource selection into the authorization window that the API provides during the authentication phase. A good example of this would be Slack's authorization window that has you select the channel inside the pop up.

I think a lot of APIs could benefit from this pattern. For example when you want to authorize an application to work with GitHub it's pretty much an all or nothing gambit when it would be much nicer if one could select a specific repository to grant access to. This also eases the experience for the end user as current workaround can be doing things like creating an API user who only has one repository whitelisted.

Solution: Include granular permissions in the user-facing authorization flow, not the API.

Get Your OAuth Butt Out of Gear

Now you're probably thinking "Alright, alright, how can I stop myself from becoming an OAuth Butt?" Thankfully there are several resources out there to aid in rolling out a stellar OAuth 2.0 API.

• While the OAuth 2.0
  specification can be a little unwieldy, Mashape has an OAuth Bible resource which provides a great, easy to follow guide with sources.
• You should also check out the OAuth 2.0 server libraries for your target language or framework, as they most likely have all the required bits baked in.
• If you're in a rush or don't want to manage this whole flow, there are several Authentication as a Service providers out there like Auth0 that can take the work off your hands.

We can’t say your API will immediately be successful when you remove OAuth Butts. However, sticking to standards and conventions will make it easier for those you do attract to integrate with your API. Like in my early days at Zapier, building out integrations, those true OAuth 2.0 APIs were always the ones I could finish quickly.

When you’re ready, add your API to the Zapier Developer Platform and help your customers connect to 750+ other apps. We can even handle most OAuth Butts–though we know that wouldn’t be you.