About this article

I am writing this because this is what I'd like to have found when I'm figuring out how OAuth works. I'm writing in hope that it would be helpful to someone, including future-me.

  • This article shouldn't be specific to Twitter. It's specific to OAuth (1.0a), an should be applicable anywhere that is.
  • This article neglects all cryptography or OAuth design decisions - those aspects belong in "Why OAuth Works The Way It Does" rather than in "How OAuth Works".
  • This article will not show any code.

I have found these two articles which helped me quite a lot in understanding OAuth - but they're still not exactly what I'd like:

I wanted there to be a storybook-like article with personified characters that represented the different parties, and this article is what I came up with. It might not be exactly correct, but it should be helpful with understanding. Please point me out if and where I'm wrong.

For more meta info, go to section "Background" way down there.

Prerequisites

  • You know what "OAuth" refers to, and have used it as a user before, e.g. have clicked a "sign in with twitter" button like the one in Attending. If you haven't, go try it out now or see Twitter's explanation.
  • Learn some words. See the OAuth spec's Definitions. I'll be using them.

The story

Update: It turned out that this section of my article is really just my own understanding and description of what's described in section 6 of the OAuth 1.0a spec - I'm glad to have found my interpretation to be quite correct!

The Consumer (Attending.io) builds his site. He then goes to the Service Provider (Twitter) and registers himself as a "Consumer" at that service. The Service Provider provides the Consumer with a Consumer Key and a Consumer Secret, which corresponds to that key.

The User visits the Consumer's site. The Consumers's site shows a "sign in with twitter" button, which the User clicks, with the purpose of letting the Consumer interact with the Service Provider on behave of himself. Now, the Consumer needs to do something in response to that click.

The Consumer now contacts the Service Provider, proves who he claims himself to be by using the matching Consumer Key and Consumer Secret, and asks for a Request Token, which comes with a corresponding Request Token Secret.

The Consumer then generates a URL based on the information from the Request Token & Secret, and redirects the User to that URL to authorize the Consumer. With Attending and Twitter, that URL would be to a page managed by Twitter, and is specific to that instance of a request of authentication, that Consumer and that User. Because the purpose of this URL is to authorize, it is called the Authorization URL.

The User now communicates directly with the Service Provider (e.g. after you clicked that button, you're now faced with a webpage with your browser's address bar showing ***.twitter.com/***.). The User says to the Service Provider, "Yep, this dude here is trustworthy. I'd like to give 'em authority to access that part'a my stuff". In response, the Service Provider nods his head, makes a note of the affair, and gives an OAuth Verifier to the User.

The User takes the OAuth Verification, leaves the Service Provider, goes to the Consumer, and says "Yep, it's done. Here's the OAuth Verification" and hands it to him.

The Consumer again grabs the Request Token & Secret together with the OAuth Verification, gives them all to the Service Provider, and ask for an Access Token and its corresponding Access Token Secret. The Service Provider checks to see that all three of the Request Token, the Request Token Secret, and the OAuth Verification actually match, and says "No problem, here are the keys", and finally gives the Consumer the Access Token and its corresponding Access Token Key.

Now is the end of (what I call) an OAuth auth session. With the Access Token & Key, the Consumer is finally authorized by the User to access Protected Resources at the Service Provider. For example, the Consumer might ask "Please go ahead and delete all my User's email", and the Service Provider might do that. Exactly what type (or say, authority level) of access the Consumer is authorized to, is proposed before the OAuth auth session takes place, and is confirmed by the User when he is at the Service Provider's place authorizing the Consumer. The User should be able to make the Service Provider revoke access of a particular Access Token.

The keys

Notice how "Key/Token" & "Secret" come in pairs. There are 3 pairs in total:

  1. the Consumer Key & Secret,
  2. the Request Token & Secret, and
  3. the Access Key & Secret.

In addition to those keys/tokens & secrets, Twitter also makes use of something called an "OAuth Verification".

According to my understanding:

  • The Consumer ~ is specific to each, well, Consumer. As long as "that app" is still operated by the same person or team, the Service Provider doesn't need to assign new ~ to "that app".
  • The Request ~ is generated every time the Consumer needs the User to grant him permission from the Service Provider. Think of the "Request" as an authorization request.
  • The Access ~ is kept by the Consumer, forever. (If you give someone information, you can ever take it back, right?) The Access ~ may lose effect at the User's wish. After the User revokes it, if he again wants to use the Consumer's app, he will have to go through the authorisation(?) process again to give the Consumer new Access ~.

Done

That's all. Now, you should be able to read spec and docs and work out how to do stuff, now that you should know most of what needs to be done.

Background

OAuth is not a new thing. I've recently been trying to understand how it works, in the context of Twitter. (That would be OAuth 1.0a, because that's what Twitter uses.)

I find it hard to figure out how OAuth works. The resources I find online about OAuth are either too specific & low-level, viz. being about the most detailed details of OAuth - e.g. the OAuth 1.0a spec, or too abstract & high-level, viz. whose intended audience seemed to be people who already knows how OAuth works - e.g. the documentation of libraries like twitter-oauth or python-twitter - they straight up refer to OAuth concepts and mention phrases like "access token" without explaining what the concepts mean.