Add IAM authentication support

Author: smithsz

src/cloudant/_2to3.py

@@ -39,6 +39,7 @@
     # pylint: disable=wrong-import-position,no-name-in-module,import-error,unused-import
     from urllib import quote as url_quote, quote_plus as url_quote_plus
     from urlparse import urlparse as url_parse
+    from urlparse import urljoin as url_join
     from ConfigParser import RawConfigParser
 
     def iteritems_(adict):
@@ -60,6 +61,7 @@ def next_(itr):
         return itr.next()
 else:
     from urllib.parse import urlparse as url_parse  # pylint: disable=wrong-import-position,no-name-in-module,import-error,ungrouped-imports
+    from urllib.parse import urljoin as url_join  # pylint: disable=wrong-import-position,no-name-in-module,import-error,ungrouped-imports
     from urllib.parse import quote as url_quote  # pylint: disable=wrong-import-position,no-name-in-module,import-error,ungrouped-imports
     from urllib.parse import quote_plus as url_quote_plus  # pylint: disable=wrong-import-position,no-name-in-module,import-error,ungrouped-imports
     from configparser import RawConfigParser  # pylint: disable=wrong-import-position,no-name-in-module,import-error

src/cloudant/__init__.py

@@ -62,6 +62,21 @@ def cloudant(user, passwd, **kwargs):
     yield cloudant_session
     cloudant_session.disconnect()
 
+@contextlib.contextmanager
+def cloudant_iam(api_key, account_name, **kwargs):
+    """
+    Provides a context manager to create a Cloudant session and provide access
+    to databases, docs etc.
+
+    :param api_key: IAM authentication API key.
+    :param account_name: Cloudant account name.
+    """
+    cloudant_session = Cloudant(account_name, api_key, use_iam=True, **kwargs)
+
+    cloudant_session.connect()
+    yield cloudant_session
+    cloudant_session.disconnect()
+
 @contextlib.contextmanager
 def cloudant_bluemix(vcap_services, instance_name=None, **kwargs):
     """

src/cloudant/_common_util.py

@@ -17,13 +17,15 @@
 throughout the library.
 """
 
+import os
 import sys
 import platform
 from collections import Sequence
 import json
-from requests import Session
+from requests import RequestException, Session
 
-from ._2to3 import LONGTYPE, STRTYPE, NONETYPE, UNITYPE, iteritems_, url_parse
+from ._2to3 import LONGTYPE, STRTYPE, NONETYPE, UNITYPE, iteritems_, url_parse, \
+    url_join
 from .error import CloudantArgumentError, CloudantException
 
 # Library Constants
@@ -276,6 +278,7 @@ def append_response_error_content(response, **kwargs):
 
 # Classes
 
+
 class _Code(str):
     """
     Wraps a ``str`` object as a _Code object providing the means to handle
@@ -287,66 +290,187 @@ def __new__(cls, code):
             return str.__new__(cls, code.encode('utf8'))
         return str.__new__(cls, code)
 
-class InfiniteSession(Session):
+
+class ClientSession(Session):
     """
-    This class provides for the ability to automatically renew session login
-    information in the event of expired session authentication.
+    This class extends Session and provides a default timeout.
+    """
+
+    def __init__(self, **kwargs):
+        super(ClientSession, self).__init__()
+        self._timeout = kwargs.get('timeout', None)
+
+    def request(self, method, url, **kwargs):  # pylint: disable=W0221
+        """
+        Overrides ``requests.Session.request`` to set the timeout.
+        """
+        resp = super(ClientSession, self).request(
+            method, url, timeout=self._timeout, **kwargs)
+
+        return resp
+
+
+class CookieSession(ClientSession):
+    """
+    This class extends ClientSession and provides cookie authentication.
     """
 
     def __init__(self, username, password, server_url, **kwargs):
-        super(InfiniteSession, self).__init__()
+        super(CookieSession, self).__init__(**kwargs)
         self._username = username
         self._password = password
-        self._server_url = server_url
-        self._timeout = kwargs.get('timeout', None)
+        self._auto_renew = kwargs.get('auto_renew', False)
+        self._session_url = url_join(server_url, '_session')
+
+    def info(self):
+        """
+        Get cookie based login user information.
+        """
+        resp = self.get(self._session_url)
+        resp.raise_for_status()
+
+        return resp.json()
+
+    def login(self):
+        """
+        Perform cookie based user login.
+        """
+        resp = super(CookieSession, self).request(
+            'POST',
+            self._session_url,
+            data={'name': self._username, 'password': self._password},
+        )
+        resp.raise_for_status()
+
+    def logout(self):
+        """
+        Logout cookie based user.
+        """
+        resp = super(CookieSession, self).request('DELETE', self._session_url)
+        resp.raise_for_status()
 
     def request(self, method, url, **kwargs):  # pylint: disable=W0221
         """
-        Overrides ``requests.Session.request`` to perform a POST to the
-        _session endpoint to renew Session cookie authentication settings and
-        then retry the original request, if necessary.
+        Overrides ``requests.Session.request`` to renew the cookie and then
+        retry the original request (if required).
         """
-        resp = super(InfiniteSession, self).request(
-            method, url, timeout=self._timeout, **kwargs)
+        resp = super(CookieSession, self).request(method, url, **kwargs)
+
         path = url_parse(url).path.lower()
         post_to_session = method.upper() == 'POST' and path == '/_session'
+
+        if not self._auto_renew or post_to_session:
+            return resp
+
         is_expired = any((
             resp.status_code == 403 and
             resp.json().get('error') == 'credentials_expired',
             resp.status_code == 401
         ))
-        if not post_to_session and is_expired:
-            super(InfiniteSession, self).request(
-                'POST',
-                '/'.join([self._server_url, '_session']),
-                data={'name': self._username, 'password': self._password},
-                headers={'Content-Type': 'application/x-www-form-urlencoded'}
-            )
-            resp = super(InfiniteSession, self).request(
-                method, url, timeout=self._timeout, **kwargs)
+
+        if is_expired:
+            self.login()
+            resp = super(CookieSession, self).request(method, url, **kwargs)
 
         return resp
 
-class ClientSession(Session):
+
+class IAMSession(ClientSession):
     """
-    This class extends Session and provides a default timeout.
+    This class extends ClientSession and provides IAM authentication.
     """
 
-    def __init__(self, username, password, server_url, **kwargs):
-        super(ClientSession, self).__init__()
-        self._username = username
-        self._password = password
-        self._server_url = server_url
-        self._timeout = kwargs.get('timeout', None)
+    def __init__(self, api_key, server_url, **kwargs):
+        super(IAMSession, self).__init__(**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.
+        """
+        access_token = self._get_access_token()
+        try:
+            super(IAMSession, self).request(
+                'POST',
+                self._session_url,
+                headers={'Content-Type': 'application/json'},
+                data=json.dumps({'access_token': access_token})
+            ).raise_for_status()
+
+        except RequestException:
+            raise CloudantException(
+                'Failed to exchange IAM token with Cloudant')
+
+    def logout(self):
+        """
+        Logout IAM cookie based user.
+        """
+        self.cookies.clear()
 
     def request(self, method, url, **kwargs):  # pylint: disable=W0221
         """
-        Overrides ``requests.Session.request`` to set the timeout.
+        Overrides ``requests.Session.request`` to renew the IAM cookie
+        and then retry the original request (if required).
         """
-        resp = super(ClientSession, self).request(
-            method, url, timeout=self._timeout, **kwargs)
+        resp = super(IAMSession, self).request(method, url, **kwargs)
+
+        if not self._auto_renew or url in [self._session_url, self._token_url]:
+            return resp
+
+        is_expired = any((
+            resp.status_code == 403 and
+            resp.json().get('error') == 'credentials_expired',
+            resp.status_code == 401
+        ))
+
+        if is_expired:
+            self.login()
+            resp = super(IAMSession, self).request(method, url, **kwargs)
+
         return resp
 
+    def _get_access_token(self):
+        """
+        Get IAM access token using API key.
+        """
+        err = 'Failed to contact IAM token service'
+        try:
+            resp = super(IAMSession, self).request(
+                'POST',
+                self._token_url,
+                auth=('bx', 'bx'),  # required for user API keys
+                headers={'Accepts': 'application/json'},
+                data={
+                    'grant_type': 'urn:ibm:params:oauth:grant-type:apikey',
+                    'response_type': 'cloud_iam',
+                    'apikey': self._api_key
+                }
+            )
+            err = resp.json().get('errorMessage', err)
+            resp.raise_for_status()
+
+            return resp.json()['access_token']
+
+        except KeyError:
+            raise CloudantException('Invalid response from IAM token service')
+
+        except RequestException:
+            raise CloudantException(err)
+
+
 class CloudFoundryService(object):
     """ Manages Cloud Foundry service configuration. """