Accessing Third-Party API Resources via OAuth [Tech Treats]October 3, 2012 2012-10-03 15:11
Accessing Third-Party API Resources via OAuth [Tech Treats]
Accessing Third-Party API Resources via OAuth [Tech Treats]
The last post in this column provided an in-depth discussion on the changes mandated by the new specification of the Twitter API v1.1. Two of the major changes were a limit on the number of users per app, calculated using the number of OAuth ‘tokens’, and the requirement of OAuth for every API call rather than one session. This post describes OAuth and the process of using OAuth to access third party APIs exposed by various platforms.
OAuth, as you’d perhaps already know, is an Open standard for Authorization, a free and open protocol built on IETF standards and licenses from the Open Web Foundation. It provides a method for clients to access server resources on behalf of a resource owner without having to hand out their credentials, typically supplying authentication tokens instead. Each token grants access to a specific site for specific resources and for a predefined time-to-live. This allows a user to grant a third party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data.
OAuth provides just enough permission and just enough responsibility. An app is provided granular access so that it can do only that much permission that the user wants to do through it. App developers, who are not necessarily security experts, do not want the responsibility of holding a user’s secret information. Using OAuth, the information is stored by the provider who provides a token using which the app can access only part of the user’s data.
How does OAuth work?
The heart of OAuth is an authorization token with limited rights, which a site or a platform (the service provider, for example, Twitter) generates for an app (called consumer, like the url-shortening service, bitly) on behalf of the user (yours truly, for instance). Here is how the entire process happens:
- I visit bit.ly on the web, which users a service provided by Twitter. I already have a Twitter account, and I am already signed in on the same browser.
- I choose “Sign in with Twitter” on bitly, which uses its OAuth credentials with Twitter to begin the authentication process for me.
POST /initiate HTTP/1.1
- The Twitter server validates the request and replies with a set of temporary credentials in the body of the HTTP response, and I am redirected to
- Bitly presents me with a request to authorize access to various ‘resources’ from my Twitter account, as shown in the screengrab below. It also tells me what resources it will it not be able to access (internally, what APIs it will be unable to call on my behalf).
- After I authorize bitly to access my Twitter account, bitly stores a unique token for me with my bitly account, and redirects me to the callback uri provided by the client in the previous request.
Bitly uses the authorizations to fetch tweets from my feed that contain links shortened by bitly’s service, and lists those pages under the network tab.
The user can revoke the token at any time should they become suspicious or dissatisfied with the app.
OAuth vs OpenID
While OpenID is all about using a single identity to sign into many sites, OAuth is about giving access to your stuff without sharing your identity at all (or its secret parts, like password). In other words, OAuth is about getting users to grant access to a functionality or data (authorization) while OpenID makes sure the users are really who they say they are (authentication). OAuth attempts to provide a standard way for developers to offer their services via an API without forcing their users to expose their credentials, which OpenID mandates. OAuth is not an OpenID extension and at the specification level, shares only few things with OpenID.
OAuth began in November 2006 when Blaine Cook was developing the Twitter OpenID implementation, and was looking for a way to use OpenID with the Twitter API to delegate authentication. OAuth 1.0 was published in December 2007 and quickly become the industry standard for web-based access delegation. A minor revision (OAuth 1.0 Revision A) was published in June 2008 to fix a security hole. OAuth 1.0a is not an IETF standard but stable and well understood. Uses a form of a cryoptographic hash code to sign each API request and exchange credentials between client and server. This means that you get API security without SSL (not only is the password never exchanged but the OAuth token is never exchanged – it’s encrypted inside the signature). But coding the signature right is tricky.
OAuth 2.0 is a completely new protocol and is not backwards compatible with previous versions even though it retains the overall architecture and approach. This specification is being developed within the IETF OAuth WG and is based on the OAuth WRAP proposal. It supports a ‘bearer token’, which is easier to code than the signature but requires SSL. (However, most APIs should be using SSL by default anyway.) Optional specs support signatures, SAML, and so on, but those specs are not yet stable.
Who uses OAuth?
Both versions 1.0a and 2.0 are in use among providers. Flickr, OpenTable, LinkedIn, Netflix, Tumblr, Twitter, Vimeo, Yahoo!, and Yelp use 1.0a, while companies like bit.ly, Facebook, Foursquare, GitHub, Google, Instagram, Microsoft, Salesforce.com, and Yammer have moved on to 2.0 even though the it is not completely stable yet.
When not to use OAuth?
OAuth should not be used just because it sounds a fancy thing to do. It is not recommended for an API that does not require authentication, like catalog and search APIs that access public data. Google Maps, for example, needs to know who you are but does not bother to track what kind of addresses or directions you are looking for. So they use an API key to establish identity, but do not need authentication/ authorization. The API key does the job of tracking and limiting the number of requests being made from a particular app.
OAuth, in its typical use case, is three-legged–there are three entities: a client application, an API provider, and the user. There can also be a two-legged OAuth where the OAuth signature method is used to identify just the app and not the user, which can also be done using SSL. In most such cases, OAuth can be an overkill. [I would say this is not even OAuth, even though the OAuth specs do not say anything about the number of legs, and two-legged OAuth is a huge topic for debate among developers.]
OAuth is a very convenient and easy to use protocol, and the lifeline of thousands of app developers and companies. OAuth solves an important problem in a world where applications talk to each other via APIs–how can one app give another app API access without requiring that the user give out their password. This has allowed APIs to go in places where they could never go before. As apps and devices increase conversation among each other, OAuth is poised to become a defacto standard, and the backbone of the Internet of things.