A Primer to the OAuth Protocol

During the past several decades, Web pages have changed from being static, mostly informational tools to full-blown applications. Coinciding with this development, Web developers have created interfaces to their Web applications so that other developers could develop applications to work with the Web application. For instance, think of any application on your phone for a Web service. This is possible only because of the application programming interface (API) constructed by the Web service's developers.

An API allows developers to give others access to certain functionality of their service without losing control of their service or how it behaves. With the development of these APIs arose the issue of user authentication and security. Every time you want to do something with the service, you have to send your user credentials (typically a user ID and password). This exposes the user to interested parties and makes the authentication untrustworthy. The application used by the user also could store the password and allow another application or person access to the user's account.

Enter OAuth.

OAuth is intended to be a simple, secure way to authenticate users without exposing their secret credentials to anyone who shouldn't have access to them. It was started in November 2006 by Blaine Cook, who was working on an OpenID implementation for Twitter. While working on it, Blaine realized that the Twitter API couldn't deal with a user who had authenticated with an OpenID. He got in touch with Chris Messina in order to find a way to use OpenID with the Twitter API. After several conversations with a few other people later, OAuth was born. In December of that year, OAuth Core 1.0 was finalized.

You can think of OAuth like an ATM card. Your bank account (the Web service) has a load of services associated with it, and you can use all of them, provided you put your card in the ATM and enter your PIN. Ultimately, anyone who has your card and PIN has full access to your account and can use all those neat services to do whatever he or she wants to your account. However, you can use your card as a credit card as well, and in that case, replace your knowledge of the PIN with a signature. In this capacity, the cardholder can do only very limited transactions, namely make charges against the balance of the account.

If someone were to try to use your signature to charge something to your account without your card, it wouldn't work. If you had the card but not the signature, the same result would occur (theoretically). OAuth works in a similar manner. If an application has your signature, it can make API calls on your behalf to the Web service, but that signature works only with that application. Allowing one party to access someone else's resources on his or her behalf is the core of the OAuth protocol.

Consider user Jane, a member of a photo-sharing site, photosharingexample.com (Service Provider), where she keeps all her pictures. For Christmas, she decides to give her mother some nice prints of her family, so she signs up for an account with another site called photoprintingexample.com (Consumer). The new site, photoprintingexample.com, has a feature that allows Jane to select pictures stored in her photosharingexample.com account and transfer them to her photoprintingexample.com account to be printed.

Photoprintingexample.com already has registered for a Consumer Key and Consumer Secret from photosharingexample.com:

Consumer Key:  dpf43f3p2l4k3l03
Consumer Secret:  kd94hf93k423kf44

Jane elects to use this service. When photoprintingexample.com tries to retrieve Jane's pictures from photosharingexample.com, it receives an HTTP 401 Unauthorized error, indicating those photos are private. This is expected, because Jane hasn't authorized photoprintingexample.com access to her photosharingexample.com account yet. The Consumer sends the following request to the Service Provider:

https://photosharingexample.com/request_token?
↪oauth_consumer_key=dpf43f3p2l4k3l03&oauth_
↪signature_method=PLAINTEXT&oauth_signature=
↪kd94hf93k423kf44%26&oauth_timestamp=
↪1191242090&oauth_nonce=hsu94j3884jdopsl&oauth_version=1.0

Using nonces can be very costly for Service Providers, as they demand persistent storage of all nonce values ever received. To make server implementations less costly, OAuth adds a timestamp value to each request, which allows the Service Provider to keep nonce values only for a limited time. When a request comes in with a timestamp that is older than the retained time frame, it is rejected, because the Service Provider no longer has nonces from that time period.