Auth: Add OAuth 2.0 authentication support (atlassian-api#666)

* Auth: Add OAuth 2.0 authentication support

The current implementation only supports authentication with OAuth 1.0.
They are mostly used by the server variants. The cloud services now use
OAuth 2.0.

With this commit it is now supported without breaking the support for
OAuth 1.0.

* Auth: Documentation for OAuth 2.0 authentication

* Auth: Example for OAuth 2.0 authentication

Adds an example Flask server to show how to use the new OAuth 2.0
authentication.

* Auth: Remove trailing whitespace

* Auth: Reformatting according to qa

Author: jensvog

atlassian/rest_client.py

@@ -4,7 +4,7 @@
 
 import requests
 from oauthlib.oauth1 import SIGNATURE_RSA
-from requests_oauthlib import OAuth1
+from requests_oauthlib import OAuth1, OAuth2
 from six.moves.urllib.parse import urlencode
 
 from atlassian.request_utils import get_default_logger
@@ -45,6 +45,7 @@ def __init__(
         verify_ssl=True,
         session=None,
         oauth=None,
+        oauth2=None,
         cookies=None,
         advanced_mode=None,
         kerberos=None,
@@ -70,6 +71,8 @@ def __init__(
             self._create_basic_session(username, password)
         elif oauth is not None:
             self._create_oauth_session(oauth)
+        elif oauth2 is not None:
+            self._create_oauth2_session(oauth2)
         elif kerberos is not None:
             self._create_kerberos_session(kerberos)
         elif cookies is not None:
@@ -110,6 +113,19 @@ def _create_oauth_session(self, oauth_dict):
         )
         self._session.auth = oauth
 
+    def _create_oauth2_session(self, oauth_dict):
+        """
+        Use OAuth 2.0 Authentication
+        :param oauth_dict: Dictionary containing access information. Must at
+            least contain "client_id" and "token". "token" is a dictionary and
+            must at least contain "access_token" and "token_type".
+        :return:
+        """
+        if "client" not in oauth_dict:
+            oauth_dict["client"] = None
+        oauth = OAuth2(oauth_dict["client_id"], oauth_dict["client"], oauth_dict["token"])
+        self._session.auth = oauth
+
     def _update_header(self, key, value):
         """
         Update header for exist session

docs/index.rst

@@ -117,6 +117,26 @@ Alternatively OAuth can be used:
         url='http://localhost:8080',
         oauth=oauth_dict)
 
+OAuth 2.0 is also supported:
+
+.. code-block:: python
+
+    from atlassian.bitbucket.cloud import Cloud
+
+    # token is a dictionary and must at least contain "access_token"
+    # and "token_type".
+    oauth2_dict = {
+        "client_id": client_id,
+        "token": token}
+
+    bitbucket_cloud = Cloud(
+        url='https://api.bitbucket.org/',
+        oauth2=oauth2_dict)
+
+    # For a detailed example see bitbucket_oauth2.py in
+    # examples/bitbucket
+
+
 Or Kerberos *(installation with kerberos extra necessary)*:
 
 .. code-block:: python

examples/bitbucket/bitbucket_oauth2.py

@@ -0,0 +1,57 @@
+# Example server with Flask demonstrating use of OAuth 2.0. Server
+# needs to be deployed. Example code is requesting access token from
+# Bitbucket. User has to grant access rights. After authorization the
+# token and the available workspaces are returned.
+
+from requests_oauthlib import OAuth2Session
+from atlassian.bitbucket.cloud import Cloud
+from flask import Flask, request, redirect, session
+
+app = Flask(__name__)
+app.secret_key = ""
+
+# Bitbucket OAuth URLs
+authorization_base_url = "https://bitbucket.org/site/oauth2/authorize"
+token_url = "https://bitbucket.org/site/oauth2/access_token"
+
+# 1. Create OAuth consumer
+# Go to "Your profile and setting" -> "All workspaces" -> "Manage".
+# Go to "Apps and features" -> "OAuth consumers".
+# Click "Add consumer". Fill in Name and Callback URL. Set permissions
+# as needed. Click save and copy client id and secret.
+client_id = ""
+client_secret = ""
+
+
+# 2. Redirect to Bitbucket for authorization
+# The server request to {server_url}/login is redirected to Bitbucket.
+# The user is asked to grant access permissions.
+@app.route("/login")
+def login():
+    bitbucket = OAuth2Session(client_id)
+    authorization_url, state = bitbucket.authorization_url(authorization_base_url)
+    session["oauth_state"] = state
+    return redirect(authorization_url)
+
+
+# 3. Bitbucket sends callback with token
+# Bitbucket is calling the Callback URL specified in the OAuth
+# consumer. This should be set to {server_url}/callback. The callback
+# contains the access token.
+@app.route("/callback")
+def callback():
+    bitbucket = OAuth2Session(client_id, state=session["oauth_state"])
+    token = bitbucket.fetch_token(token_url, client_secret=client_secret, authorization_response=request.url)
+
+    return "Token: {}<p />Workspaces: {}".format(token, ", ".join(get_workspaces(token)))
+
+
+# 4. Token used for Bitbucket Python API
+# Bitbucket Cloud API library is called with token information. User is
+# authenticated with OAuth 2.0.
+def get_workspaces(token):
+    oauth2 = {"client_id": client_id, "token": token}
+
+    bitbucket = Cloud(url="https://api.bitbucket.org/", oauth2=oauth2, cloud=True)
+
+    return [ws.name for ws in bitbucket.workspaces.each()]