oauth2_provider 0.2.0 → 0.3.0

data/CHANGELOG

@@ -1,3 +1,309 @@
+[d5cc143 | Mon Feb 21 22:13:01 UTC 2011] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Move some files out of the way so they are not packaged as part of the build.
+
+[d82fa79 | Mon Feb 21 22:01:42 UTC 2011] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add development dependencies in the gemspec.
+
+[59f625d | Mon Feb 21 21:35:50 UTC 2011] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Issue #8 - add gem dependency in gemspec.
+
+    https://github.com/ThoughtWorksStudios/oauth2_provider/issues/8
+
+[48205b0 | Mon Feb 21 21:34:08 UTC 2011] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Fix the initializer as per https://github.com/ThoughtWorksStudios/oauth2_provider/issues/6
+
+[184421a | Tue Feb 08 23:31:19 UTC 2011] Badrinath Janakiraman <Admin@arvo.corporate.thoughtworks.com>
+
+  * added the ssl ignore flag to application_controller methods
+
+[0ccb704 | Tue Feb 08 20:19:08 UTC 2011] Badrinath Janakiraman <Admin@arvo.corporate.thoughtworks.com>
+
+  * change the logic which determines whether ssl checks should be enforced to use an independent boolean flag
+
+[05ed98a | Tue Feb 08 19:25:08 UTC 2011] Badrinath Janakiraman <Admin@arvo.corporate.thoughtworks.com>
+
+  * Monkey patch AP request class to return true for :ssl? if DISABLE_OAUTH_SSL environment variable is set
+
+[f623329 | Thu Jan 06 23:41:36 UTC 2011] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * make transaction on model base return the block yield result
+
+[9d02bb9 | Thu Jan 06 22:47:34 UTC 2011] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * update model_base to make it sync with gadeget rendering server plugin
+
+[cfd06e9 | Tue Jan 04 20:46:35 UTC 2011] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * #193 - make the oauth plugin transaction safe by adding an around filter on the controller that sets up a transaction.
+
+[a8319df | Mon Dec 20 19:18:15 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Fix for #147 - "Click in the 'Do you wish to allow ...' line on the authorize screen causes the browser to authorize the oauth request". This was regressed in rev ea0e2e77.
+
+[6de7348 | Sat Dec 18 00:10:41 UTC 2010] David Rice <djrice@phydeaux3.corporate.thoughtworks.com>
+
+  * rename oauth client help link keyname to something sensible
+
+[9a6cc65 | Fri Dec 17 19:48:54 UTC 2010] Luau <luaupair@luau-pair-01.corporate.thoughtworks.com>
+
+  * fix bug #128
+
+[26bf9ce | Fri Dec 17 19:02:10 UTC 2010] Luau <luaupair@luau-pair-01.corporate.thoughtworks.com>
+
+  * #162 make oauth_allowed using class inherit attributes
+
+[8cc8796 | Tue Dec 14 21:52:27 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Remove SSL requirement on the oauth user tokens page. Also remove the token from being displayed in the web page.
+
+[2a35528 | Tue Dec 14 20:21:04 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Do not try to parse a blank url.
+
+[433e388 | Tue Dec 14 20:20:43 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Render an error message ont he oauth provider page when accessing the page over ssl, but ssl_base_url is not set.
+
+[cdbb55b | Tue Dec 14 19:31:43 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Fix all that were broken because of the change in the way the ssl helper works with respect to redirects.
+
+[5adf33b | Tue Dec 14 19:02:28 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Show the correct urls on the oauth clients page. These urls are generated using the base ssl site url instead of guessing it from the request params.
+
+[6a683d1 | Tue Dec 14 01:47:31 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Change the ssl url generation to explicitly use ssl_base_url instead of guessing it from the request hostname.
+
+[ea75b58 | Sat Dec 11 01:20:02 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * #192 - Do not allow oauth requests(using Authorization header) over plain text protocol.
+
+[fc70f28 | Thu Dec 09 20:29:34 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Handle leading and trailing slashes in routes admin and user prefixes.
+
+[4b3e151 | Wed Oct 27 20:06:25 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Change the name and ID of the hidden field.
+
+[2c04217 | Thu Dec 09 01:39:03 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * #190 - Do not allow creating multiple oauth authorization codes for a user and client combination.
+
+[4a4904f | Thu Dec 09 01:28:14 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * #185 - Do not allow creating multiple oauth access tokens for a user and client combination.
+
+[2f8fa3f | Wed Dec 08 01:04:49 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Some metaprogramming foo to extract configuration properties into a helper.
+
+[6273ae6 | Tue Dec 07 23:44:32 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Explicitly add the namespace to avoid any conflicts.
+
+[ec59f83 | Tue Dec 07 23:26:38 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Hide the environment variable for ssl port behind a configuration object. This will allow for registering a proc that can be evaluated at a later time.
+
+[e14d225 | Tue Dec 07 22:24:18 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * Add some tests around redirecting to ssl port if ssl is enabled. The port number is not put in the url if the port is 443.
+
+[6d9789d | Wed Dec 01 23:14:16 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * add a missing period for user token revoke flash message
+
+[96dca17 | Wed Dec 01 22:22:05 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * flash message for revoke user tokens
+
+[cc996f0 | Wed Dec 01 22:14:04 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * revoke and revoke_by_admin actions support a passed in redirect url
+
+[083a2a7 | Wed Dec 01 21:51:21 UTC 2010] Luau <luaupair@luau-pair-02.corporate.thoughtworks.com>
+
+  * require validatable explicitly because const_missing not work correctly in thread safe mode
+
+[fedc33f | Wed Dec 01 00:02:13 UTC 2010] David Rice <djrice@phydeaux3.corporate.thoughtworks.com>
+
+  * finish #122; admins can now delete all tokens belonging to a particular user
+
+[b9d9ff2 | Tue Nov 30 23:32:41 UTC 2010] David Rice <djrice@phydeaux3.corporate.thoughtworks.com>
+
+  * #122 (sorta); provide admin function for deleting any token regardless of whether it is owned by currently logged in user
+
+[85b5d20 | Tue Oct 26 20:59:02 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Change styling on the oauth authorize page. This also fixes #147
+
+[6ac0a39 | Wed Oct 20 17:58:36 UTC 2010] Jen Marley <jen.marley@gmail.com>
+
+  * updated h1 title to make 'client' to be plural
+
+[85acd26 | Thu Oct 14 21:58:23 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add some css layout into all pages.
+
+[ea0e2e7 | Thu Oct 14 20:53:39 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add HTML IDs and labels on the authorize page.
+
+[41db763 | Thu Oct 14 18:22:09 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Change some UI/css bits.
+
+[af62696 | Wed Oct 13 20:38:33 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Change some styling bits.
+
+[f216d85 | Thu Sep 30 18:33:16 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Remove the word mingle from one of the forms.
+
+[4eccf59 | Wed Sep 29 23:22:51 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Update the notice file and the gem task to package the notice file.
+
+[0a041b2 | Wed Sep 29 23:11:42 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Remove the help link in the error message.
+
+[98c24f5 | Wed Sep 29 23:11:19 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Change some wording on the oauth clients page.
+
+[5042141 | Tue Sep 28 23:36:19 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Fixed some messages.
+
+[a525c20 | Tue Sep 28 18:49:19 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Strip the fields in the oauth client before saving them. Is is to sanitize inputs coming from the controllers.
+
+[55a6258 | Tue Sep 28 18:44:42 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add a before_save hook into model base.
+
+[409a595 | Tue Sep 28 18:01:20 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Package all the files, there was one file that we missed during packaging.
+
+[e76bc4e | Tue Sep 28 00:14:19 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add some styling around the summary information on the oauth clients page.
+
+[75ee0e0 | Tue Sep 28 00:13:57 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add a line break for the buttons on the authorize pages.
+
+[8e6ce06 | Mon Sep 27 22:10:22 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Change order of table columns on the oauth_clients page. The redirect url comes after the provider name.
+
+[1f8c818 | Mon Sep 27 22:05:52 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * HTML escape input fields on the oauth
+
+[6284989 | Mon Sep 27 21:44:08 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Provide additional information about OAuth endpoints on the clients page.
+
+[a9266c2 | Mon Sep 27 21:25:04 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add ability to disable SSL validation on controllers.
+
+[2d0391b | Mon Sep 27 21:22:23 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Force SSL on all controllers.
+
+[a5e0754 | Mon Sep 27 20:51:50 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add a sslhelper to force SSL access on controllers that include the ssl_helper.
+
+[c9bb474 | Mon Sep 27 17:48:26 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * cosmetic changes:
+
+    * Add a span inside the delete link, so that apps can hide the text and use an icon for the link instead.
+
+[8bacec5 | Fri Sep 24 23:08:10 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Remove all namespaces from the controllers. This is done because rails routes do not play nice with the namespaces in controller classnames.
+
+[1489d1c | Fri Sep 24 22:51:15 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Remove all namespaces from the controllers. This is done because rails routes do not play nice with the namespaces in controller classnames.
+
+[3aafe41 | Thu Sep 23 22:41:16 UTC 2010] joshuacronemeyer <jrc@thoughtworks.com>
+
+  * Fixed a bug with an object was not valid, but did not provide any validation errors.
+
+    Also removed some redundant code to improve readability.
+
+[45a6e6a | Thu Sep 23 21:54:27 UTC 2010] joshuacronemeyer <jrc@thoughtworks.com>
+
+  * fixed bug where comparing ids not working because id wasn't being stored as an integer.
+
+[4cf3b38 | Thu Sep 23 21:03:07 UTC 2010] joshuacronemeyer <jrc@thoughtworks.com>
+
+  * Redirect URI duplicates should be allowed.
+
+[ec4c2e8 | Wed Sep 22 23:37:52 UTC 2010] joshuacronemeyer <jrc@thoughtworks.com>
+
+  * fixed issue with the oauth popup containing bad form submit params.
+
+[b913d4d | Wed Sep 22 00:50:01 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * added ability to do validates_uniqueness_of checks for ModelBase and added unique fields to OauthClient
+
+[3e43894 | Tue Sep 21 23:30:43 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * List OAuth clients by name.
+
+[5fe8087 | Tue Sep 21 23:30:29 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * Changed help links in all pages.
+
+[1100a00 | Tue Sep 21 18:25:44 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * Remove usage of all magical routes, use explicit controller and action names.
+
+[a9464c4 | Tue Sep 21 00:41:50 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * Change the wording on the authorization page to make it an explicit 'yes' or 'no' answer, instead of a checkbox.
+
+[22a91a4 | Tue Sep 21 00:33:11 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * Change some styling and rendering to match what mingle uses.
+
+[154eff4 | Tue Sep 21 00:24:58 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * Change some styling and rendering to match what mingle uses.
+
+[474fff9 | Mon Sep 20 23:06:55 UTC 2010] Bill DePhillips <bill.dephillips@gmail.com>
+
+  * removed datasource message
+
+[8c596aa | Thu Sep 09 23:24:48 UTC 2010] wdephillips <ThoughtWorks@WD4382s-MacBook-Pro.local>
+
+  * Bill/WPC allow basic auth in host sample app, make host sample app ui more selenium friendly
+
+[5f93768 | Wed Sep 08 04:20:30 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add RESTful API access for accessing oauth clients.
+
+[df04fa5 | Wed Sep 01 00:35:47 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
+
+  * Add a check for valid id when saving a new object. Postgres does not know how to cast a nil to an integer type.
+
 [f15eb88 | Tue Aug 31 23:25:50 UTC 2010] Ketan Padegaonkar <KetanPadegaonkar@gmail.com>
 
   * Bumping up version number for a 0.2.0 release!

data/HACKING.textile

@@ -0,0 +1,45 @@
+h1. Hacking on the OAuth2 Provider
+
+This plugin is tested with:
+* Rails v2.3.4
+* MRI 1.8.7 and JRuby 1.5.1
+
+Dependencies:
+* See the gemspec in "https://github.com/ThoughtWorksStudios/oauth2_provider/blob/master/provider/vendor/plugins/oauth2_provider/tasks/gem.rake":gem.rake a list of known dependencies
+
+h2. Getting up and running
+
+ $ git clone git://github.com/ThoughtWorksStudios/oauth2_provider.git
+
+For MRI:
+
+ $ [sudo] gem install rcov saikuro_treemap validatable --no-rdoc --no-ri
+
+For JRuby, nothing more is needed, JRuby 1.5.1 and all necessary gems
+are bundled in the /tools directory
+
+h2. Structure of the code
+
+ /tools - contains JRuby + dependency gems
+ /provider - a sample rails app containing the plugin
+ /provider/test - contains the unit+functional tests
+ /provider/vendor/plugins/oauth2_provider - the actual plugin
+
+h2. Hacking on code
+
+ $ cd provider
+ $ # muck around with code
+ $ rake #using MRI
+ $ script/jruby -S rake #using the bundled JRuby
+
+h2. Metrics
+
+ $ cd provider
+ $ rake test:coverage
+ $ rake metrics:saikuro_treemap
+
+h2. Pushing out gems
+
+ $ cd provider
+ $ script/jruby -S rake release:push        # follow the instructions printed by the task
+ $ script/jruby -S gem push pkg/oauth2_provider-VERSION.gem

data/NOTICE.textile

@@ -0,0 +1,6 @@
+h2. List of 3rd party dependencies and their licenses
+
+This project depends on the following 3rd party code:
+
+| *Name*      | *What it does*        | *Version* | *Authors*   | *URL*                             | *License*    | *License URL*                            |
+| validatable | Validation of inputs  | 1.6.7     | Jay Fields  | http://validatable.rubyforge.org  | Ruby License | http://www.ruby-lang.org/en/LICENSE.txt  |

data/README.textile

@@ -44,8 +44,10 @@ h1. Supported Features
 * Endpoint for clients to request authorization 'code'
 * Endpoint to request an access token using the authorization 'code'
 * Admin screens for:
- * End users to manage/revoke access tokens given out to 3rd party OAuth2 clients
- * Admins to manage OAuth2 clients
+** End users to manage/revoke access tokens given out to 3rd party OAuth2 clients
+** Admins to manage OAuth2 clients
+* Admin controller actions for:
+** Delete a single token belonging to any user
 
 h1. Available Endpoint URLs
 
@@ -58,9 +60,12 @@ See config/routes.rb in the plugin for more details.
 *Accessed from the browser*
 * /oauth/user_tokens (Oauth2::Provider::OauthUserTokensController) - used by end users to view and revoke access to 3rd party OAuth2 clients.
 * /oauth/clients (Oauth2::Provider::OauthClientsController) - to manage oauth clients (should be available only to admins)
+* /oauth/user_tokens/revoke_by_admin (Oauth2::Provider::OauthUserTokensController) - used by users with admin privileges to revoke any one token (pass token_id param), or all tokens belonging to a single user (pass user_id param).
 
 It is the responsibility of the host application to avoid routing conflicts. The simplest thing to do is avoid defining any paths starting with /oauth
 
+It is also the responsibility to restrict access to admin-only features such as /oauth/user_tokens/revoke_by_admin
+
 h1. Installation
 
  $ [sudo] gem install oauth2_provider
@@ -102,7 +107,7 @@ h3. Rails initializer
 Edit the file config/initializers/oauth2_provider.rb in which you
 * must call filter skipping methods on OauthTokenController, ensuring any authentication filters to not run for this controllers actions
 * must setup authorization for OauthClientsController, limiting access to only application administrators
-* must setup authorization for OauthUserTokensController, limiting access to logged in users  (this step might not actually require you to write code, we're just putting it here to make sure you consider this issue)
+* must setup authorization for OauthUserTokensController actions, limiting access to all actions to logged in users (this part might come for free), and access to revoke_by_admin to administrators.
 * might call filter skipping or similar methods on the other provided controllers should it be necessary for them to run
 
 A sample initializer:
@@ -117,6 +122,9 @@ module Oauth2
     # use host app's custom authorization filter to protect OauthClientsController
     OauthClientsController.before_filter(:ensure_admin_user)
     
+    # use host app's custom authorization filter to protect admin actions on OauthUserTokensController
+    OauthUserTokensController.before_filter(:ensure_admin_user, :only => [:revoke_by_admin])
+    
   end
 end
 </pre>

data/WHAT_IS_OAUTH.textile

@@ -0,0 +1,165 @@
+h1. OAuth Provider
+
+* Owns a (password) protected resource that belongs to a user.
+* Generates keys(client_id, client_secret, redirect_uri) for OAuth clients. 
+
+h1. OAuth Client
+
+* Wants to access the protected resource on any OAuth Provider.
+* Knows its own client_id, and client_secret, redirect_uri
+
+h1. The admin flow
+
+h3. admin@oauth-client:
+
+* Writes to admin@oauth-provider to request access, and sends a
+ redirect_uri and application_name as part of the process.
+
+h3. admin@oauth-provider:
+
+* Logs in into an admin screen to register an oauth client with the
+  redirect_uri and application_name.
+
+* Sends back the the client_id and client_secret that the admin screen
+  generated to admin@oauth-client.
+
+Now the oauth provider and oauth clients know about each other.
+
+h1. The end user flow
+
+NOTE: this flow is over-simplified, and omits a lot of headers for the sake
+of simplicity. Also all URLs SHOULD be HTTPS, or security goes out the door,
+anyone can sniff codes and tokens going over the wire.
+
+* Bob(bob@gmail.com) has an account at an OAuth provider - flickr.com.
+* Bob(bob@hotmail.com) also has an account on another service - printer.com.
+
+Note that it's the same Bob, but he has a different username and identity
+on flickr.com and printer.com.
+
+Bob now wants his protected resources (pictures) on the flickr.com (OAuth
+provider) to be accessible by printer.com(OAuth client) so that they can
+print it.
+
+* Bob logs in into printer.com and logs in using the browser.
+* Bob clicks on a link that says "Print pictures from flickr.com"
+* The link takes Bob's browser to
+  
+  Location:
+  
+    http://flickr.com/authorize?
+      client_id=PRINTER_DOT_COM_CLIENT_ID&
+      redirect_uri=PRINTER_DOT_COM_REDIRECT_URI
+
+
+
+* The authorization step:
+
+  * flickr.com knows the application_name corresponding to the client_id and
+    redirect_uri and asks Bob to log in. Once Bob is logged in, flickr.com 
+    asks Bob in the browser:
+  
+    Do you wish to allow a service named 'printer.com' to access flickr.com
+    on your behalf? [Y/N]
+  
+    [SUBMIT]
+
+    If Bob clicks yes and hits submit to allow printer.com to access his
+    private data on flickr.com on his behalf.
+  
+    Note that Bob does not tell either his flickr.com username/password to
+    printer.com.
+    
+  * Once Bob clicks yes and authorizes access, flickr.com generates a 
+    ONE_TIME_AUTHORIZATION_CODE_FOR_BOB for printer.com to access
+    bob@gmail.com's data on bob@hotmail.com's behalf.
+    
+    flickr.com now redirects Bob's browser to the redirect_uri with the
+    authorization_code:
+  
+    Bob redirected to:
+    
+      http://printer.com/callback?code=ONE_TIME_AUTHORIZATION_CODE_FOR_BOB
+
+
+
+* Getting an access_token in exchange for ONE_TIME_AUTHORIZATION_CODE_FOR_BOB
+
+  * printer.com now gets a callback with the authorization code, and knows
+    that Bob is logged in, therefore ONE_TIME_AUTHORIZATION_CODE_FOR_BOB
+    belongs to bob@hotmail.com.
+  
+  * Now that printer.com knows the authorization_code, it can request an
+    access_token from flickr.com to actually access the protected
+    resource.
+    
+  * printer.com contacts flickr.com, gives the authorization_code to get
+    back an access_token.
+    
+    printer.com identifies itself to flickr.com and requests an access_token
+    corresponding to ONE_TIME_AUTHORIZATION_CODE_FOR_BOB
+  
+      http://flickr.com/oauth/token?
+        client_id=PRINTER_DOT_COM_CLIENT_ID&
+        client_secret=PRINTER_DOT_COM_CLIENT_SECRET&
+        code=ONE_TIME_AUTHORIZATION_CODE_FOR_BOB
+
+  * flickr.com reads the request, and verifies that the client_id,
+    client_secret, ONE_TIME_AUTHORIZATION_CODE_FOR_BOB are all consistent
+    
+    It then generates an access_token for printer.com to be able to access
+    Bob's pictures, and renders a json containing the access_token:
+    
+    {
+     access_token: ACCESS_TOKEN_FOR_PRINTER_TO_ACCESS_BOBS_PICTURES,
+     ...
+     ...
+    }
+  
+  * once printer.com gets this response, it stores this access_token and knows
+    that it is used to access Bob's pictures. Alice will have her own access
+    token, once she goes through the same flow as Bob.
+
+
+
+* printer.com accessing Bob's pictures now
+
+  * Bob says he wants to print sunset.jpg on flickr.com
+  
+  * printer.com to flickr.com:
+  
+    get: flickr.com/images/bob/sunset.jpg?
+      access_token=ACCESS_TOKEN_FOR_PRINTER_TO_ACCESS_BOBS_PICTURES
+      
+    flickr.com verifies the access_token and knows it was given out to Bob,
+    the image belongs to Bob, all is well and it renders the sunset.jpg
+    image so that printer.com can print it.
+
+
+Shown as a picture:
+
+<pre>
++----------+          Client Identifier      +---------------+
+|         -+----(A)--- & Redirect URI ------>|               |
+| End-user |                                 |     OAuth     |
+|    at    |<---(B)-- User authenticates --->|    Provider   |
+| Browser  |                                 |               |
+|         -+----(C)-- Authorization Code ---<|               |
++-|----|---+                                 +---------------+
+  |    |                                         ^   v   ^
+ (A)  (C)                                        |   |   |
+  |    |                                         |   |   |
+  ^    v                                         |   |   |
++---------+                                      |   |   |
+|         |>---(D)-- Client Credentials, --------'   |   |
+|  OAuth2 |          Authorization Code,             |   |
+|  Client |            & Redirect URI                |   |
+|         |                                          |   |
+|         |<---(E)----- Access Token ----------------'   |
+|         |       (w/ Optional Refresh Token)            |
+|         |                                              |
+|         |>---(F)------ Send Access Token --------------'
+|         |                Get back data
+|         |                for end user
++---------+
+</pre>