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 walkthrough 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...
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 faji.com 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.
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 beppa.com and begins to order prints. Beppa supports importing images from many photo sharing sites, including Faji. Jane selects the photos source and clicks Continue.
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.
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 http://beppa.com/order.>
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.
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 beppa.com.
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.
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 http://beppa.com/order 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.
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.
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.
