Oauth workflows

README.rst

@@ -3,176 +3,49 @@ Requests-OAuthlib
 
 This project provides first-class OAuth library support for `Requests <http://python-requests.org>`_.
 
-The OAuth workflow
-------------------
+The OAuth 1 workflow
+--------------------
 
-OAuth can seem overly complicated and it sure has its quirks. Luckily,
+OAuth 1 can seem overly complicated and it sure has its quirks. Luckily,
 requests_oauthlib hides most of these and let you focus at the task at hand.
 
-You will be forced to go through a few steps when you are using OAuth. Below is an
-example of the most common OAuth workflow using HMAC-SHA1 signed requests where
-the signature is supplied in the Authorization header.
-
-The example assumes an interactive prompt which is good for demonstration but in
-practice you will likely be using a web application (which makes authorizing much
-less awkward since you can simply redirect).
-
-0. Manual client signup with the OAuth provider (i.e. Google, Twitter) to get
-   a set of client credentials. Usually a client key and secret. Client might sometimes
-   be referred to as consumer. For example:
-
-.. code-block:: pycon
-
-    >>> from __future__ import unicode_literals
-    >>> import requests
-    >>> from requests_oauthlib import OAuth1
-
-    >>> client_key = '...'
-    >>> client_secret = '...'
-
-1. Obtain a request token which will identify you (the client) in the next step.
-   At this stage you will only need your client key and secret.
-
-.. code-block:: pycon
-
-    >>> oauth = OAuth1(client_key, client_secret=client_secret)
-    >>> request_token_url = 'https://api.twitter.com/oauth/request_token'
-    >>> r = requests.post(url=request_token_url, auth=oauth)
-    >>> r.content
-    "oauth_token=Z6eEdO8MOmk394WozF5oKyuAv855l4Mlqo7hhlSLik&oauth_token_secret=Kd75W4OQfb2oJTV0vzGzeXftVAwgMnEK9MumzYcM"
-    >>> from urlparse import parse_qs
-    >>> credentials = parse_qs(r.content)
-    >>> resource_owner_key = credentials.get('oauth_token')[0]
-    >>> resource_owner_secret = credentials.get('oauth_token_secret')[0]
-
-2. Obtain authorization from the user (resource owner) to access their protected
-   resources (images, tweets, etc.). This is commonly done by redirecting the
-   user to a specific url to which you add the request token as a query parameter.
-   Note that not all services will give you a verifier even if they should. Also
-   the oauth_token given here will be the same as the one in the previous step.
-
-.. code-block:: pycon
-
-    >>> authorize_url = 'https://api.twitter.com/oauth/authorize?oauth_token='
-    >>> authorize_url = authorize_url + resource_owner_key
-    >>> print 'Please go here and authorize,', authorize_url
-    >>> verifier = raw_input('Please input the verifier')
-
-3. Obtain an access token from the OAuth provider. Save this token as it can be
-   re-used later. In this step we will re-use most of the credentials obtained
-   uptil this point.
-
-.. code-block:: pycon
-
-    >>> oauth = OAuth1(client_key,
-                       client_secret=client_secret,
-                       resource_owner_key=resource_owner_key,
-                       resource_owner_secret=resource_owner_secret,
-                       verifier=verifier)
-    >>> access_token_url = 'https://api.twitter.com/oauth/access_token'
-    >>> r = requests.post(url=access_token_url, auth=oauth)
-    >>> r.content
-    "oauth_token=6253282-eWudHldSbIaelX7swmsiHImEL4KinwaGloHANdrY&oauth_token_secret=2EEfA6BG3ly3sR3RjE0IBSnlQu4ZrUzPiYKmrkVU"
-    >>> credentials = parse_qs(r.content)
-    >>> resource_owner_key = credentials.get('oauth_token')[0]
-    >>> resource_owner_secret = credentials.get('oauth_token_secret')[0]
-
-4. Access protected resources. OAuth1 access tokens typically do not expire
-   and may be re-used until revoked by the user or yourself.
+Accessing protected resources using requests_oauthlib is as simple as:
 
 .. code-block:: pycon
 
-    >>> oauth = OAuth1(client_key,
-                       client_secret=client_secret,
-                       resource_owner_key=resource_owner_key,
-                       resource_owner_secret=resource_owner_secret)
+    >>> from requests_oauthlib import OAuth1Session
+    >>> twitter = OAuth1Session('client_key',
+                                client_secret='client_secret',
+                                resource_owner_key='resource_owner_key',
+                                resource_owner_secret='resource_owner_secret')
     >>> url = 'https://api.twitter.com/1/account/settings.json'
-    >>> r = requests.get(url=url, auth=oauth)
-    >>> # Enjoy =)
-
-
-Signature placement - header, query or body?
---------------------------------------------
-
-OAuth takes many forms, so let's take a look at a few different forms:
-
-.. code-block:: python
-
-    import requests
-    from requests_oauthlib import OAuth1
+    >>> r = twitter.get(url)
 
-    url = u'https://api.twitter.com/1/account/settings.json'
+Before accessing resources you will need to obtain a few credentials from your
+provider (i.e. Twitter) and authorization from the user for whom you wish to
+retrieve resources for. You can read all about this in the full
+`OAuth 1 workflow guide on RTD <http://requests-oauthlib.readthedocs.org/en/latest/oauth1_workflow.html>`_.
 
-    client_key = u'...'
-    client_secret = u'...'
-    resource_owner_key = u'...'
-    resource_owner_secret = u'...'
+The OAuth 2 workflow
+--------------------
 
+OAuth 2 is generally simpler than OAuth 1 but comes in more flavours. The most
+common being the Authorization Code Grant, also known as the WebApplication
+flow.
 
-Header signing (recommended):
+Fetching a protected resource after obtaining an access token can be as simple as:
 
-.. code-block:: python
-
-    headeroauth = OAuth1(client_key, client_secret,
-                         resource_owner_key, resource_owner_secret,
-                         signature_type='auth_header')
-    r = requests.get(url, auth=headeroauth)
-
-
-
-Query signing:
-
-.. code-block:: python
-
-    queryoauth = OAuth1(client_key, client_secret,
-                        resource_owner_key, resource_owner_secret,
-                        signature_type='query')
-    r = requests.get(url, auth=queryoauth)
-
-
-Body signing:
-
-.. code-block:: python
-
-    bodyoauth = OAuth1(client_key, client_secret,
-                       resource_owner_key, resource_owner_secret,
-                       signature_type='body')
-
-    r = requests.post(url, auth=bodyoauth)
-
-
-Signature types - HMAC (most common), RSA, Plaintext
-----------------------------------------------------
-
-OAuth1 defaults to using HMAC and examples can be found in the previous
-sections.
-
-Plaintext work on the same credentials as HMAC and the only change you will
-need to make when using it is to add signature_type='PLAINTEXT'
-to the OAuth1 constructor:
-
-.. code-block:: python
-
-    headeroauth = OAuth1(client_key, client_secret,
-                         resource_owner_key, resource_owner_secret,
-                         signature_method='PLAINTEXT')
-
-RSA is different in that it does not use client_secret nor
-resource_owner_secret. Instead it uses public and private keys. The public key
-is provided to the OAuth provider during client registration. The private key
-is used to sign requests. The previous section can be summarized as:
-
-.. code-block:: python
-
-    key = open("your_rsa_key.pem").read()
+.. code-block:: pycon
 
-    queryoauth = OAuth1(client_key, signature_method=SIGNATURE_RSA,
-                        rsa_key=key, signature_type='query')
-    headeroauth = OAuth1(client_key, signature_method=SIGNATURE_RSA,
-                        rsa_key=key, signature_type='auth_header')
-    bodyoauth = OAuth1(client_key, signature_method=SIGNATURE_RSA,
-                        rsa_key=key, signature_type='body')
+    >>> from requests_oauthlib import OAuth2Session
+    >>> google = OAuth2Session('client_id', token='token')
+    >>> url = 'https://www.googleapis.com/oauth2/v1/userinfo'
+    >>> r = google.get(url)
 
+Before accessing resources you will need to obtain a few credentials from your
+provider (i.e. Google) and authorization from the user for whom you wish to
+retrieve resources for. You can read all about this in the full
+`OAuth 2 workflow guide on RTD <http://requests-oauthlib.readthedocs.org/en/latest/oauth2_workflow.html>`_.
 
 Installation
 -------------
@@ -182,4 +55,3 @@ To install requests and requests_oauthlib you can use pip:
 .. code-block:: bash
 
     $ pip install requests requests_oauthlib
-

docs/index.rst

@@ -11,6 +11,8 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   oauth1_workflow
+   oauth2_workflow
    api