OAuth is awesome, OAuth is horrible.
After writing the Runscope API, and several OAuth API clients to other services. I’ve finally had some time to figure out how I feel about OAuth 2.0… OAuth is awesome, OAuth is horrible.
My co-founder John has already written a lot on OAuth Implementations. So, I won’t cover those specific APIs and how they use OAuth. Instead I’d like to talk at a high level about the experience interacting with both sides of the OAuth equation.
OAuth is awesome
The concept of delegating access of your data without sharing credentials is AWESOME. OAuth is prerequisite for ecosystem building. If you don’t want a community of applications and developers that work together, you don’t need an OAuth API. OAuth Applications are by and large, web applications. Web applications are probably the easiest to build, distribute, and discover.
An application you build for yourself can be easily used by others without having to share code or modify authentication configuration. This fundamentally changes the user experience from the old-world model of “download this tarball and modify the user/auth token or give me your login info” to a much more frictionless “click here for new functionality!” This creates a strong network effect; as the number of easily shared applications grows, the more everyone can benefit from the new functionality without additional work.
Building a community around your API also magnifies the reach of niche features. If you’re building a strong ecosystem of developers, highlighting and encouraging community contributions is essential. There are always more feature ideas than you can possibly implement by yourself.
OAuth is also great as a user when you can properly reason about scopes and permissions. Empowering the data owner to control access to their own information is crucial in building trust. There’s a reason you shouldn’t hand over your username and password for you Gmail account to everyone who wants it. The same goes for your API access. OAuth gives you the option to define levels of comfort and trust that are not binary.
Overall, the end-user experience of OAuth is great when done right. And it turns siloed and fragmented web services into a more connected and powerful network of applications.
OAuth is horrible
Writing an OAuth powered API is still too much work. A minimal implementation is still many hundreds of lines of code. There’s so much boilerplate code, e.g. ‘required’ parameters that end up largely vestigial for most implementations. There are very few OAuth 2.0 provider libraries, and most libraries I’ve seen have very poor documentation and are usually barebones implementations. Which means if you want to support ‘optional’ parameters or other types, you’re going to have to roll your own anyway.
OAuth requires a lot of server side state. Storing authorization codes, access tokens, application client_ids, scopes, are all necessary. This is another reason why adding OAuth to your API is more work than it seems initially. Do you create database tables for everything? Do you expire authorization codes or access tokens? Now you have to use redis/memcache to automatically expire data or build an entirely new system cleanup your database tables. These are the hidden costs of OAuth implementations. Unexpected details that crop up halfway through an implementation will cause an engineer to pull their hair out.
Any OAuth provider’s documentation has to start from the foundations of OAuth. You can’t assume that all developers that show up at your API have heard of and/or built OAuth clients before. This means your documentation is now many pages longer than it would have been originally. There is no “1 line demo” that gets you up and running if you’re building an OAuth powered app.
Building simple apps takes a lot of work. There are many libraries that aim to help, but they are framework specific, and still require much thought on how to integrate.
To start, you’ve got to setup an application with the service provider. Usually this requires some information about your application, URLs for making callbacks to, website urls, names, etc. There’s a bit of upfront setup work before you can even test out an OAuth API.
Furthermore, OAuth Clients have to be Servers as well. The main OAuth flow is a web based flow. It requires you to setup a full fledged server and register routes that can be redirected to. This adds complexity to an application beyond “set the username and password in your http client”.
If you are running multiple environments, (i.e local dev/integration/production), you must duplicate the upfront setup of creating different applications with different redirect URLs. Not to mention the challenges of managing OAuth applications details in a team environment where multiple people need access to view and update them.
Sanding off the Rough Edges
We use OAuth for the Runscope API, but to make it easier on app developers we’ve added a few features to help reduce the friction on building new Apps.
Personal Access Tokens
When you create an application, we immediately authorize it against your own account. We show you on the Application page an access token (and setup our Request Editor) so that you can easily test making API calls right away without having to build any OAuth flow code.
Authorize URL Builder
When building a new app, setting up the proper redirects with all the correct parameters is non-trivial. We’ve added a URL builder that lets you select which scopes you want to request and automatically populates your client_id, callback_url, and other required parameters.
Multiple Callback URLs
One application can have more than one callback URL associated with it. We check for valid a redirect_uri against the list on the application, if any one matches then we proceed with the OAuth flow. This lets you set callback URLs for your local, test, and production environments on the same Application. No need to switch out client_ids or client secrets if you don’t want to.
For other OAuth2 APIs, we’ve built a token generator that can help in the development / debugging process.
There are also some other OAuth aggregator tools out there. Services like foauth and oauth.io help ease the pain of developer setup work, and their existence is further proof that OAuth isn’t easy to get right.
OAuth is awesome for consumers once you get passed the pain of developing against it. Every day the global API community grows by making it easier to try new concepts, build great applications, and share data and ideas with other individuals. Our mission at Runscope is to help all API developers navigate the world of HTTP and HTTP APIs, and our OAuth related tools take a step in that direction. Growing a healthy ecosystem of API providers and developers will help fuel the next round of innovation on the web.