Beginner’s Guide to OAuth – Part II : Protocol Workflow

OAuth is best explained with real-life examples. The specification includes in Appendix A a similar example but focuses on the HTTP calls syntax. This walk-through demonstrates a typical OAuth session and includes the perspectives of the User, Consumer, and Service Provider. The websites and people mentioned are fictional. The Scottish references are real. And so our story begins…

Flow Step 1

Jane is back from her Scotland vacation. She spent 2 weeks on the island of Islay sampling Scotch. When she gets back home, Jane wants to share some of her vacation photos with her friends. Jane uses Faji, a photo sharing site, for sharing journey photos. She signs into her account, and uploads two photos which she marks private.

Using OAuth terminology, Jane is the User and Faji the Service Provider. The 2 photos Jane uploaded are the Protected Resources.

Flow Screen 1

After sharing her photos with a few of her online friends, Jane wants to also share them with her grandmother. She doesn’t want to share her rare bottle of Scotch with anyone. But grandma doesn’t have an internet connection so Jane plans to order prints and have them mailed to grandma. Being a responsible person, Jane uses Beppa, an environmentally friendly photo printing service.

Using OAuth terminology, Beppa is the Consumer. Since Jane marked the photos as private, Beppa must use OAuth to gain access to the photos in order to print them.

Jane visits and begins to order prints. Beppa supports importing images from many photo sharing sites, including Faji. Jane selects the photos source and clicks Continue.

Flow Screen 2

When Beppa added support for Faji photo import, a Beppa developer known in OAuth as a Consumer Developer obtained a Consumer Key and Consumer Secret from Faji to be used with Faji’s OAuth-enabled API.

After Jane clicks Continue, something important happens in the background between Beppa and Faji. Beppa requests from Faji a Request Token. At this point, the Request Token is not User-specific, and can be used by Beppa to gain User approval from Jane to access her private photos.

Flow Step 2

Jane clicked Continue and is now waiting for her screen to change. She sips from her prized Black Bowmore while waiting for the next page to load.

When Beppa receives the Request Token, it redirects Jane to the Faji OAuth User Authorization URL with the Request Token and asks Faji to redirect Jane back once approval has been granted to

Jane has been redirected to Faji and is requested to sign into the site. OAuth requires that Service Providers first authenticate the User, and then ask them to grant access to the Consumer.

Jane notices she is now at a Faji page by looking at the browser URL, and enters her username and password.

Flow Screen 3

OAuth allows Jane to keep her username and password private and not share them with Beppa or any other site. At no time does Jane enters her credentials into

After successfully logging into Faji, Jane is asked to grant access to Beppa, the Consumer. Faji informs Jane of who is requesting access (in this case Beppa) and the type of access being granted. Jane can approve or deny access.

Jane makes sure Beppa is getting the limited access it needs. She does not want to allow Beppa to change her photos or do anything else to them. She also notes this is a onetime access good for one hour which should be enough time for Beppa to fetch her photos.

Flow Screen 4

Once Jane approves the request, Faji marks the Request Token as User-authorized by Jane. Jane’s browser is redirected back to Beppa, to the URL previously provided together with the Request Token. This allows Beppa to know it can now continue to fetch Jane’s photos.

Jane waits for Beppa to present her with her photos fetched from her Faji account.

Flow Screen 5

While Jane waits, Beppa uses the authorized Request Token and exchanges it for an Access Token. Request Tokens are only good for obtaining User approval, while Access Tokens are used to access Protected Resources, in this case Jane’s photos. In the first request, Beppa exchanges the Request Token for an Access Token and in the second (can be multiple requests, one for a list of photos, and a few more to get each photo) request gets the photos.

Flow Step 3

When Beppa is done, Jane’s browser refreshes to complete the order.

Beppa successfully fetched Jane’s photo. They are presented as thumbnails for her to pick and place her order.

Jane is very impressed how Beppa grabbed her photos without asking for her username and password. She likes what she sees and place the print order.

Flow Screen 6

44 thoughts on “Beginner’s Guide to OAuth – Part II : Protocol Workflow

  1. Love your use of Islay as your Scottish references! Even the pictures are fitting, with the Paps of Jura on one of them. Not to forget the Bowmore whisky.

  2. Isn’t there an opportunity for an unscrupulous site to go ‘phishing’ in this scenario?
    The user, almost certainly blind drunk, is clicking a link (continue button) on one site (beppa), which could then redirect to something that appears to be the faji authentication screen (and may not be)…then entering their username and password for that site.
    There’s a big difference between trusting a site with your username/password and trusting that they won’t dupe you with a ‘phishing’ attack…but would Jock McBloggs know the difference?

  3. Hi, I’m currently evaluating how to use OAUTH to implement the acct sharing feature in our site Currently we allow
    acct sharing w/ trusted friends or family w/o telling them your passwords, similar idea to OAUTH. BUT WE DON’T NEED ANY SITE TO CHANGE
    OR COOP WITH US, mashed life works w/ virtually ANY site instantly.
    My boss’ concern is that – OAUTH requires the participating sites to adapt to accept OAUTH, it is a looong shot and nobody knows how long it will take.
    So I’m crafting a way to leverage the elegance of OAUTH but w/o any site to change to adapt to us. Does anyone have similar experience like mine? We can put our work as a OAUTH accelerator or extension.
    Thanks for tips… I’m a newbie to OAUTH.

  4. I’m not sure what the hold-up is… maybe they have re-thought their stance on how this is going to actually make the company any money. Or perhaps their lawyers pointed out the liability of providing agents a platform to stick their feet in their mouth. Whatever it is, it’s hardly something I’d claim as being “Well done”.

  5. Very nice article, that explain clearly with a real example how we can use OAuth!
    I’m curious to know how is possible to load info for different url, but I’ll read more on the specification 😉

  6. The authorization on second site (the Service Provider) doesn’t and shouldn’t use username/password authorization through same media, which is http in this case. It should use something like OpenID, and use XMPP (Jabber) to ask user for authorization.
    Then you will be protected from “phishing” as Armin describe.
    So OpenID (as single sign on on the web with user authorization through another channel like XMPP) and OAuth will work well and more secure that how it is done these days.
    With this it’s no need to give Customer site your username/password or make data public that should not be public to make Customer and Service Sites to coöperate smoothly with each other.

  7. @Michael, I guess it is a delicate balance between usability of the overall system and super-tight security (how much do you trust your browser to render pages and accept entries into fields?)
    There are at least two ways out to your dilemma.
    1) Use OpenID but then the user would have to know that she needs to open an uncompromised browser window and type in the URL of the OpenID dispenser. Sophisticated users that are very concerned about their online privacy would go for it, but I doubt that your Jock McBloggs would be up to the challenge.
    2) Add security on the Service Provider site and decorate the user account login with a user chosen icon/thumbnail. A phishing site would have a hard time guessing this pre-agreed secret between the User and the Service Provider in order to give the impression that the user talks to the Service Provider when she actually interacts with
    Also keep in mind that Jane will trust Beppa originally.

  8. It’s Official: Mashup Privacy Protocol OAuth Is Fair Game

    OAuth, the open authorization protocol standard that will let users give limited access to their data to third party websites without giving away their passwords, crossed an important threshold tonight. All parties involved in building the spec have si…

  9. @Joerg: re: phishing login pages – Yahoo are currently doing something similar, so that for each computer you use to access the internet, you customize the login page with an image you upload (eg, your photo, etc). The idea is that a phishing site would not be able to show this custom image, so you’d know it’s not a legit login. However, I think it is all cookies based, so if you blow cookies away, the login reverts to the non-customized look.

  10. Great example – but it is not clear to me, from the example above, HOW the “exchange” of the authorized Request Token for the Access Token is accomplished.

    Is there expectation that the Access Token is returned by RESPONSE or by REDIRECT – or is this simply an implementation specific issue and not addressed by the spec?

  11. Hi,
    what is the advantage of exchanging the request token for an access token? In other words, why does the protocol not just say: Send the authorized request token and you will get the photos?

    • The request token is sent via the browser and is exposed to the end-user while the access token is only visible to the client in direct communication. It also helps clients without the ability to receive callbacks use OAuth.

  12. Awesome !! Simple and to the point.. Neatly explained…
    I am very new to all protocols and stuff, so a silly doubt . Wats the use of the Consumer ker and consumer secret key!! To get the request token?

  13. I dont understand the part where “In the first request, Beppa exchanges the Request Token for an Access Token”. Does Beppa exchange the Request token for an Access Token or rather use the Request Token to identify itself to the service provider and the then it receives Access token

  14. In this example Jane needs to actively sign in and authorize beppa to get access to the protected resources. Is it possible to automate this process? ex. A marketing system that wants to print online stored photos

    • The whole point is to require the user to actively authorize access. You can automate this if you can reach sufficient trust and authentication with the third part (marketing system) to trust them to gain access while bypassing explicit user authorization.

Comments are closed.