Added HTTP basic authentication support

Author: smithsz

CHANGES.rst

@@ -1,5 +1,6 @@
 Unreleased
 ==========
+- [NEW] Added HTTP basic authentication support.
 - [NEW] Added ``Result.all()`` convenience method.
 - [NEW] Allow ``service_name`` to be specified when instantiating from a Bluemix VCAP_SERVICES environment variable.
 - [IMPROVED] Updated ``posixpath.join`` references to use ``'/'.join`` when concatenating URL parts.

src/cloudant/client.py

@@ -16,10 +16,14 @@
 Top level API module that maps to a Cloudant or CouchDB client connection
 instance.
 """
-import base64
 import json
 
-from ._2to3 import bytes_, unicode_
+from .client_session import (
+    BasicSession,
+    ClientSession,
+    CookieSession,
+    IAMSession
+)
 from .database import CloudantDatabase, CouchDatabase
 from .feed import Feed, InfiniteFeed
 from .error import (
@@ -31,7 +35,6 @@
     append_response_error_content,
     CloudFoundryService,
     )
-from client_session import ClientSession, CookieSession, IAMSession
 
 
 class CouchDB(dict):
@@ -67,6 +70,8 @@ class CouchDB(dict):
         `Requests library timeout argument
         <http://docs.python-requests.org/en/master/user/quickstart/#timeouts>`_.
         but will apply to every request made using this client.
+    :param bool use_basic_auth: Keyword argument, if set to True performs basic
+        access authentication with server. Default is False.
     :param bool use_iam: Keyword argument, if set to True performs
         IAM authentication with server. Default is False.
         Use :func:`~cloudant.client.CouchDB.iam` to construct an IAM
@@ -86,7 +91,9 @@ def __init__(self, user, auth_token, admin_party=False, **kwargs):
         self._timeout = kwargs.get('timeout', None)
         self.r_session = None
         self._auto_renew = kwargs.get('auto_renew', False)
+        self._use_basic_auth = kwargs.get('use_basic_auth', False)
         self._use_iam = kwargs.get('use_iam', False)
+
         connect_to_couch = kwargs.get('connect', False)
         if connect_to_couch and self._DATABASE_CLASS == CouchDatabase:
             self.connect()
@@ -100,7 +107,16 @@ def connect(self):
             self.session_logout()
 
         if self.admin_party:
-            self.r_session = ClientSession(timeout=self._timeout)
+            self.r_session = ClientSession(
+                timeout=self._timeout
+            )
+        elif self._use_basic_auth:
+            self.r_session = BasicSession(
+                self._user,
+                self._auth_token,
+                self.server_url,
+                timeout=self._timeout
+            )
         elif self._use_iam:
             self.r_session = IAMSession(
                 self._auth_token,
@@ -146,9 +162,6 @@ def session(self):
 
         :returns: Dictionary of session info for the current session.
         """
-        if self.admin_party:
-            return None
-
         return self.r_session.info()
 
     def session_cookie(self):
@@ -157,29 +170,33 @@ def session_cookie(self):
 
         :returns: Session cookie for the current session
         """
-        if self.admin_party:
-            return None
         return self.r_session.cookies.get('AuthSession')
 
     def session_login(self, user=None, passwd=None):
         """
         Performs a session login by posting the auth information
         to the _session endpoint.
+
+        :param str user: Username used to connect to CouchDB.
+        :param str auth_token: Authentication token used to connect to CouchDB.
         """
-        if self.admin_party:
-            return
+        self.change_credentials(user=user, auth_token=passwd)
+
+    def change_credentials(self, user=None, auth_token=None):
+        """
+        Change login credentials.
 
-        self.r_session.set_credentials(user, passwd)
+        :param str user: Username used to connect to CouchDB.
+        :param str auth_token: Authentication token used to connect to CouchDB.
+        """
+        self.r_session.set_credentials(user, auth_token)
         self.r_session.login()
 
     def session_logout(self):
         """
         Performs a session logout and clears the current session by
         sending a delete request to the _session endpoint.
         """
-        if self.admin_party:
-            return
-
         self.r_session.logout()
 
     def basic_auth_str(self):
@@ -189,13 +206,7 @@ def basic_auth_str(self):
 
         :returns: Basic http authentication string
         """
-        if self.admin_party:
-            return None
-        hash_ = base64.urlsafe_b64encode(bytes_("{username}:{password}".format(
-            username=self._user,
-            password=self._auth_token
-        )))
-        return "Basic {0}".format(unicode_(hash_))
+        return self.r_session.base64_user_pass()
 
     def all_dbs(self):
         """

src/cloudant/client_session.py

@@ -15,13 +15,13 @@
 """
 Module containing client session classes.
 """
-
+import base64
 import json
 import os
 
 from requests import RequestException, Session
 
-from ._2to3 import url_join
+from ._2to3 import bytes_, unicode_, url_join
 from .error import CloudantException
 
 
@@ -30,11 +30,34 @@ class ClientSession(Session):
     This class extends Session and provides a default timeout.
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, username=None, password=None, session_url=None, **kwargs):
         super(ClientSession, self).__init__()
+
+        self._username = username
+        self._password = password
+        self._session_url = session_url
+
+        self._auto_renew = kwargs.get('auto_renew', False)
         self._timeout = kwargs.get('timeout', None)
 
-    def request(self, method, url, **kwargs):  # pylint: disable=W0221
+    def base64_user_pass(self):
+        """
+        Composes a basic http auth string, suitable for use with the
+        _replicator database, and other places that need it.
+
+        :returns: Basic http authentication string
+        """
+        if self._username is None or self._password is None:
+            return None
+
+        hash_ = base64.urlsafe_b64encode(bytes_("{username}:{password}".format(
+            username=self._username,
+            password=self._password
+        )))
+        return "Basic {0}".format(unicode_(hash_))
+
+    # pylint: disable=arguments-differ
+    def request(self, method, url, **kwargs):
         """
         Overrides ``requests.Session.request`` to set the timeout.
         """
@@ -43,27 +66,75 @@ def request(self, method, url, **kwargs):  # pylint: disable=W0221
 
         return resp
 
+    def info(self):
+        """
+        Get session information.
+        """
+        if self._session_url is None:
+            return None
 
-class CookieSession(ClientSession):
+        resp = self.get(self._session_url)
+        resp.raise_for_status()
+        return resp.json()
+
+    def set_credentials(self, username, password):
+        """
+        Set a new username and password.
+
+        :param str username: New username.
+        :param str password: New password.
+        """
+        if username is not None:
+            self._username = username
+
+        if password is not None:
+            self._password = password
+
+    def login(self):
+        """
+        No-op method - not implemented here.
+        """
+        pass
+
+    def logout(self):
+        """
+        No-op method - not implemented here.
+        """
+        pass
+
+
+class BasicSession(ClientSession):
     """
-    This class extends ClientSession and provides cookie authentication.
+    This class extends ClientSession to provide basic access authentication.
     """
 
     def __init__(self, username, password, server_url, **kwargs):
-        super(CookieSession, self).__init__(**kwargs)
-        self._username = username
-        self._password = password
-        self._auto_renew = kwargs.get('auto_renew', False)
-        self._session_url = url_join(server_url, '_session')
+        super(BasicSession, self).__init__(
+            username=username,
+            password=password,
+            session_url=url_join(server_url, '_session'),
+            **kwargs)
 
-    def info(self):
+    def request(self, method, url, **kwargs):
         """
-        Get cookie based login user information.
+        Overrides ``requests.Session.request`` to provide basic access
+        authentication.
         """
-        resp = self.get(self._session_url)
-        resp.raise_for_status()
+        return super(BasicSession, self).request(
+            method, url, auth=(self._username, self._password), **kwargs)
 
-        return resp.json()
+
+class CookieSession(ClientSession):
+    """
+    This class extends ClientSession and provides cookie authentication.
+    """
+
+    def __init__(self, username, password, server_url, **kwargs):
+        super(CookieSession, self).__init__(
+            username=username,
+            password=password,
+            session_url=url_join(server_url, '_session'),
+            **kwargs)
 
     def login(self):
         """
@@ -83,7 +154,7 @@ def logout(self):
         resp = super(CookieSession, self).request('DELETE', self._session_url)
         resp.raise_for_status()
 
-    def request(self, method, url, **kwargs):  # pylint: disable=W0221
+    def request(self, method, url, **kwargs):
         """
         Overrides ``requests.Session.request`` to renew the cookie and then
         retry the original request (if required).
@@ -105,42 +176,21 @@ def request(self, method, url, **kwargs):  # pylint: disable=W0221
 
         return resp
 
-    def set_credentials(self, username, password):
-        """
-        Set a new username and password.
-
-        :param str username: New username.
-        :param str password: New password.
-        """
-        if username is not None:
-            self._username = username
-
-        if password is not None:
-            self._password = password
-
 
 class IAMSession(ClientSession):
     """
     This class extends ClientSession and provides IAM authentication.
     """
 
     def __init__(self, api_key, server_url, **kwargs):
-        super(IAMSession, self).__init__(**kwargs)
+        super(IAMSession, self).__init__(
+            session_url=url_join(server_url, '_iam_session'),
+            **kwargs)
+
         self._api_key = api_key
-        self._auto_renew = kwargs.get('auto_renew', False)
-        self._session_url = url_join(server_url, '_iam_session')
         self._token_url = os.environ.get(
             'IAM_TOKEN_URL', 'https://iam.bluemix.net/oidc/token')
 
-    def info(self):
-        """
-        Get IAM cookie based login user information.
-        """
-        resp = self.get(self._session_url)
-        resp.raise_for_status()
-
-        return resp.json()
-
     def login(self):
         """
         Perform IAM cookie based user login.
@@ -164,7 +214,7 @@ def logout(self):
         """
         self.cookies.clear()
 
-    def request(self, method, url, **kwargs):  # pylint: disable=W0221
+    def request(self, method, url, **kwargs):
         """
         Overrides ``requests.Session.request`` to renew the IAM cookie
         and then retry the original request (if required).
@@ -191,7 +241,7 @@ def request(self, method, url, **kwargs):  # pylint: disable=W0221
 
         return resp
 
-    # pylint: disable=arguments-differ
+    # pylint: disable=arguments-differ, unused-argument
     def set_credentials(self, username, api_key):
         """
         Set a new IAM API key.

src/cloudant/database.py

@@ -94,11 +94,13 @@ def creds(self):
 
         :returns: Dictionary containing authentication information
         """
-        if self.admin_party:
+        session = self.client.session()
+        if session is None:
             return None
+
         return {
             "basic_auth": self.client.basic_auth_str(),
-            "user_ctx": self.client.session()['userCtx']
+            "user_ctx": session.get('userCtx')
         }
 
     def exists(self):