Best Practices for OAuth 2.0 vs. OAuth 1.0 - One year later »

Since we first wrote about OAuth 1.0 vs. 2.0 a while back, lots has been happening and lots has changed. The OAuth community has made progress and made changes, and an increasing number of API providers have deployed APIs that use OAuth 2.0. (Similarly, the number of new OAuth 1.0-enabled APIs doesn't seem to be growing.)

We've been busy helping our customers implement OAuth-based APIs, and we've also been watching the process develop. Here are some things that we've learned: 

OAuth is a solution -- not technology.

In order for an API provider to support OAuth, a number of things have to happen. There must be a place where the OAuth protocol is actually implemented -- all of the different URLs for requesting tokens, issuing tokens, redirecting browsers, and so on. This part is a matter of implementing the standard and doesn't change from implementation to implementation (so, it can be delegated to a third-party component like Apigee Enterprise).

In addition, there has to be somewhere to store OAuth tokens. There is no standard for this -- some use an RDBMS, some use NoSQL, and others use a cloud-hosted service.

Finally, the OAuth solution has to integrate with a provider's "login page," so that when a user wants to get an OAuth token, they are redirected to a legitimate "login" page with a proper SSL certificate,  look and feel, and so on. All of these kinds of things can be different from one provider to another.

At Apigee, we have been working with many companies to deploy APIs built using OAuth. What we've found is that OAuth is not just a technology that you buy or download -- it's a bit of technology and a bit of integration, and to implement it at all you need a platform that can flexibly integrate with what you already have, while adding what you might be missing. 

Be careful.

Since we last blogged about it, OAuth 2.0 has been improved a bit and has changed some basic things -- for instance the name on the HTTP "Authorization" header has changed from "OAuth" to "Bearer." This is a big change, and obviously if an API provider just switches from one value to another without warning, all the clients will break.

OAuth 2.0 is up to draft 13, and with every draft it gets closer to being "done" -- but it's not done yet and I haven't seen anyone say when it will be. That means that if you implement, say, draft 13, you will likely have to change, and find a way to maintain backward compatibility for existing clients.

If that's too much, then implement OAuth 1.0a -- it's as "done" as it's going to get at this point! 

Stick with "bearer tokens" for now in conjunction with SSL.

The latest draft includes support for various types of security tokens,  and a mechanism to plug in new types. The simplest are "bearer tokens." A bearer token is just a big, random string that a client must present on every API call. Bearer tokens are simple because there's no special signature or validation code required on either end. The client is responsible for storing the token in a safe place and sending it with every request. The server is responsible for looking up the token in a database and making sure it's a valid one -- that's it.

However, bearer tokens provide no security unless used in conjunction with SSL -- otherwise, any eavesdropper in a coffee shop can snatch OAuth tokens from  the air. (Fortunately, OAuth tokens can be individually revoked without requiring a password reset.) 

Get ready to change -- or stick with 1.0a.

We said this before but it bears repeating -- if you implement OAuth 2.0, it is likely that you will have to change your servers to support newer versions, and also maintain backward compatibility.

One way to ease the pain is to put version numbers in the URLs that you hand out for the various steps in the OAuth flow. So, instead of using:

http://api.foo.com/oauth/authorize

use:

http://api.foo.com/oauth/13/authorize

because you know that there will be future versions and that they will be different...

Get ready for more options.

 Part of the OAuth 2.0 work defines some new security token types other than "bearer." Right now only "bearer" seems to be sufficiently mature from a spec standard, but this will change over the next few months. Here are some of the options:

1.       Bearer -- as we mentioned before, this is just a long, random string. The advantage is that it's extremely easy to implement on both client and server. The disadvantage is that it requires SSL for all API calls. Also, if API traffic passes through multiple endpoints such as proxies, then the proxies will be able to see the token as it passes by.

2.       Mac -- this is equivalent to the token scheme in OAuth 1.0, in that it requires both a key and secret, and uses an "Hmac" algorithm to encrypt some data on each request. The result is that the request is only valid if both client and server have the same keys, and there is no way for an intermediary to re-create the original request without a password. In other words, it is secure even if SSL is not used or even if the request is intercepted by a proxy.

3.       SAML -- this uses SAML assertions on each request as a way to establish the client's identity. This is helpful if you already have SAML infrastructure for either the client or server in your environment.

Top Differences between OAuth 1.0 and OAuth 2.0 for API Calls »

OAuth 1.0 (the current spec version is 1.0a, which fixes a security problem with 1.0) solves an important problem in the world of APIs -- how one web application can give another application API access without requiring that the user give out their password. OAuth 1.0 solves this problem in a clever way through a secure handshake, via API calls, between the two applications. This has allowed APIs to go in places where they could never go before.

OAuth 1.0 works by ensuring that the API client and server share a token, which is like a username, and a token secret, which is like a password. The client must generate a "signature" on every API call by encrypting a bunch of unique information using the token secret. The server must generate the same signature, and only grant access if both signatures match.

The advantage of this approach is that there is no way to find out the token secret, because it is always encrypted when it's sent over the network, and only the client and server have the keys. It doesn't matter if the data is eavesdropped on a WiFi network in Starbucks or captured by a proxy like Apigee -- there's no way to see the secret, so there's no way to impersonate the client based on what's sent over the network. All of this is done without requiring SSL, since SSL can slow down the client and server alike, and make deployment of the API server more complex.

However, both client and server developers found the complexity of generating and validating signatures to be too much. There are many tricky things that a developer must get right, down to exactly what type of "URL Encoding" is used (it's not exactly the same as it's used in other places). If the client or server makes a single tiny mistake in the signature, it's invalid and it's hard to figure out what went wrong.

OAuth 2.0 promises to simplify this stuff in a number of ways:

1. SSL is required for all the communications required to generate the token. This is a huge decrease in complexity because those complex signatures are no longer required.
2. Signatures are not required for the actual API calls once the token has been generated -- SSL is also strongly recommended here.
3. Once the token was generated, OAuth 1.0 required that the client send two security tokens on every API call, and use both to generate the signature. OAuth 2.0 has only one security token, and no signature is required.
4. It is clearly specified which parts of the protocol are implemented by the "resource owner," which is the actual server that implements the API, and which parts may be implemented by a separate "authorization server." That will make it easier for products like Apigee to offer OAuth 2.0 support to existing APIs.

For these reasons, OAuth 2.0 has already been adopted by companies like Facebook, which uses the draft spec in its Graph API. Of course, it's a new spec, which means there are new requirements and use cases that make it more complex. For instance, OAuth 2.0 also clearly lays out how to use OAuth entirely inside a browser using JavaScript that has no way to securely store a token, and it explains at a high level how to use it on a mobile phone or even on a device that has no web browser at all.

Finally, although the developers of the world will not miss generating OAuth 1.0 signatures, they served a purpose, because they allowed a client to send its token and secret securely to a server without requiring SSL. For APIs and devices that do not want to support SSL for performance or complexity reasons, signatures are still a good choice. Right now, signatures have been removed from the OAuth 2.0 spec, but they'll be added to a separate extension spec at some point.

So should you use OAuth 2.0 today? Here are a few things to consider: 

• Spec changes. OAuth 2.0 has not reached a stable IETF draft yet. If you implement it today, are you prepared to change your implementation every few weeks until the committee has agreed on a stable version? OAuth 1.0a, on the other hand, is already a well-defined standard that's not going to change any time soon.  
• Implementations. There are a number of code libraries for both client and server that support 1.0a today. There aren't as many for 2.0, so you're going to have to build more stuff on your own.
• Complexity. There's no doubt that 2.0 is easier to implement both on the client and server side.
• Performance. If you are unwilling or unable to use SSL for all of your API traffic, then OAuth 2.0 is not a good choice until some sort of signature extension is added to the spec. OAuth 1.0a already supports signatures, which are complex but allow you to securely exchange tokens without requiring the use of SSL.

You can also check out my blog on "When to Use OAuth" for more, and we'll continue to explore this issue as it evolves.  

Explore the Facebook API and Simplify OAuth 2.0 »

We launched a new tool at Apigee-  the API lifecycle management platform we offer free to the community. We've created a Facebook Graph API Console- a whole new way to interact with, learn and debug the Graph API that lets you easily view requests/responses to the API, share what you are seeing and dig into errors.

The console supports OAuth 2.0 so you can log in using your Facebook credentials- check out the video: 

InsideFacebook has some great coverage by Josh Constine out today on the console and how it works; you can also hop over to the Apigee blog for more details.