documentation/manual/en/module_specs/Zend_Oauth-ProtocolWorkflow.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.oauth.introduction.protocol-workflow">
   4     <title>Protocol Workflow</title>
   5
   6     <para>
   7         Before implementing OAuth it makes sense to understand how the protocol operates. To do so
   8         we'll take the example of Twitter which currently implements OAuth based on the OAuth Core
   9         1.0 Revision A Specification. This example looks at the protocol from the perspectives of
  10         the User (who will approve access), the Consumer (who is seeking access) and the Provider
  11         (who holds the User's private data). Access may be read-only or read and write.
  12     </para>
  13
  14     <para>
  15         By chance, our User has decided that they want to utilise a new service called TweetExpress
  16         which claims to be capable of reposting your blog posts to Twitter in a manner of seconds.
  17         TweetExpress is a registered application on Twitter meaning that it has access to a Consumer
  18         Key and a Consumer Secret (all OAuth applications must have these from the Provider they
  19         will be accessing) which identify its requests to Twitter and that ensure all requests can
  20         be signed using the Consumer Secret to verify their origin.
  21     </para>
  22
  23     <para>
  24         To use TweetExpress you are asked to register for a new account, and after your registration
  25         is confirmed you are informed that TweetExpress will seek to associate your Twitter account
  26         with the service.
  27     </para>
  28
  29     <para>
  30         In the meantime TweetExpress has been busy. Before gaining your approval from Twitter, it
  31         has sent a HTTP request to Twitter's service asking for a new unauthorized Request Token.
  32         This token is not User specific from Twitter's perspective, but TweetExpress may use it
  33         specifically for the current User and should associate it with their account and store it
  34         for future use. TweetExpress now redirects the User to Twitter so they can approve
  35         TweetExpress' access. The URL for this redirect will be signed using TweetExpress' Consumer
  36         Secret and it will contain the unauthorized Request Token as a parameter.
  37     </para>
  38
  39     <para>
  40         At this point the User may be asked to log into Twitter and will now be faced with a Twitter
  41         screen asking if they approve this request by TweetExpress to access Twitter's API on the
  42         User's behalf. Twitter will record the response which we'll assume was positive. Based on
  43         the User's approval, Twitter will record the current unauthorized Request Token as having
  44         been approved by the User (thus making it User specific) and will generate a new value in
  45         the form of a verification code. The User is now redirected back to a specific callback URL
  46         used by TweetExpress (this callback URL may be registered with Twitter or dynamically set
  47         using an oauth_callback parameter in requests). The redirect URL will contain the newly
  48         generated verification code.
  49     </para>
  50
  51     <para>
  52         TweetExpress' callback URL will trigger an examination of the response to determine whether
  53         the User has granted their approval to Twitter. Assuming so, it may now exchange it's
  54         unauthorized Request Token for a fully authorized Access Token by sending a request back to
  55         Twitter including the Request Token and the received verification code. Twitter should now
  56         send back a response containing this Access Token which must be used in all requests used to
  57         access Twitter's API on behalf of the User. Twitter will only do this once they have
  58         confirmed the attached Request Token has not already been used to retrieve another Access
  59         Token. At this point, TweetExpress may confirm the receipt of the approval to the User and
  60         delete the original Request Token which is no longer needed.
  61     </para>
  62
  63     <para>
  64         From this point forward, TweetExpress may use Twitter's API to post new tweets on the User's
  65         behalf simply by accessing the API endpoints with a request that has been digitally signed
  66         (via HMAC-SHA1) with a combination of TweetExpress' Consumer Secret and the Access Key being
  67         used.
  68     </para>
  69
  70     <para>
  71         Although Twitter do not currently expire Access Tokens, the User is free to deauthorize
  72         TweetExpress from their Twitter account settings. Once deauthorized, TweetExpress' access
  73         will be cut off and their Access Token rendered invalid.
  74     </para>
  75 </sect2>