Merge pull request #64 from Cumulocity-IoT/feature/interactive-sessions

Feature/interactive sessions

Author: chsou

.gitignore

@@ -9,3 +9,4 @@ build*
 .env*
 _version.py
 wordlist.txt
+.ipynb_checkpoints

c8y_api/__init__.py

@@ -6,7 +6,14 @@
 
 from importlib.metadata import version
 
-from c8y_api._base_api import ProcessingMode, CumulocityRestApi, HttpError, UnauthorizedError, AccessDeniedError
+from c8y_api._base_api import (
+    ProcessingMode,
+    CumulocityRestApi,
+    HttpError,
+    UnauthorizedError,
+    MissingTfaError,
+    AccessDeniedError,
+)
 from c8y_api._main_api import CumulocityApi
 from c8y_api._registry_api import CumulocityDeviceRegistry
 from c8y_api._auth import HTTPBasicAuth, HTTPBearerAuth

c8y_api/_base_api.py

@@ -16,6 +16,7 @@
 
 from c8y_api._auth import HTTPBearerAuth
 from c8y_api._jwt import JWT
+from c8y_api._util import validate_base_url
 
 
 class ProcessingMode:
@@ -40,6 +41,12 @@ def __init__(self, method: str, url: str = None, message: str = "Unauthorized.")
         super().__init__(method, url, 401, message)
 
 
+class MissingTfaError(UnauthorizedError):
+    """Error raised for unauthorized access."""
+    def __init__(self, method: str, url: str = None, message: str = "Missing TFA Token."):
+        super().__init__(method, url, message)
+
+
 class AccessDeniedError(HttpError):
     """Error raised for denied access."""
     def __init__(self, method: str, url: str = None, message: str = "Access denied."):
@@ -69,30 +76,28 @@ class CumulocityRestApi:
     CONTENT_MANAGED_OBJECT = 'application/vnd.com.nsn.cumulocity.managedobject+json'
     CONTENT_MEASUREMENT_COLLECTION = 'application/vnd.com.nsn.cumulocity.measurementcollection+json'
 
-    def __init__(self, base_url: str, tenant_id: str, username: str = None, password: str = None, tfa_token: str = None,
+    def __init__(self, base_url: str, tenant_id: str, username: str = None, password: str = None,
                  auth: AuthBase = None, application_key: str = None, processing_mode: str = None):
         """Build a CumulocityRestApi instance.
 
-        One of `auth` or `username/password` must be provided. The TFA token
-        parameter is only sensible for basic authentication.
+        One of `auth` or `username/password` must be provided.
 
         Args:
             base_url (str):  Cumulocity base URL, e.g. https://cumulocity.com
             tenant_id (str):  The ID of the tenant to connect to
             username (str):  Username
             password (str):  User password
-            tfa_token (str):  Currently valid two-factor authorization token
             auth (AuthBase):  Authentication details
             application_key (str):  Application ID to include in requests
                 (for billing/metering purposes).
             processing_mode (str);  Connection processing mode (see
                 also https://cumulocity.com/api/core/#processing-mode)
         """
-        self.base_url = base_url.rstrip('/')
+        self.base_url = validate_base_url(base_url)
+        self.is_tls = self.base_url.startswith('https')
         self.tenant_id = tenant_id
         self.application_key = application_key
         self.processing_mode = processing_mode
-        self.is_tls = self.base_url.startswith('https')
 
         if auth:
             self.auth = auth
@@ -103,14 +108,49 @@ def __init__(self, base_url: str, tenant_id: str, username: str = None, password
         else:
             raise ValueError("One of 'auth' or 'username/password' must be defined.")
 
-        self.__default_headers = {}
-        if tfa_token:
-            self.__default_headers['tfatoken'] = tfa_token
-        if self.application_key:
-            self.__default_headers[self.HEADER_APPLICATION_KEY] = self.application_key
-        if self.processing_mode:
-            self.__default_headers[self.HEADER_PROCESSING_MODE] = self.processing_mode
-        self.session = self._create_session()
+        self._session = None
+
+    @property
+    def session(self) -> requests.Session:
+        """Provide session."""
+        if not self._session:
+            self._session = self._create_session()
+        return self._session
+
+    @classmethod
+    def authenticate(
+            cls,
+            base_url: str,
+            tenant_id: str,
+            username: str,
+            password: str,
+            tfa_token: str = None,
+    ) -> (str, str):
+        """Authenticate a user using OAI Secure login method.
+
+        Args:
+            base_url (str):  Cumulocity base URL, e.g. https://cumulocity.com
+            tenant_id (str):  The ID of the tenant to connect to
+            username (str):  Username
+            password (str):  User password
+            tfa_token (str):  Currently valid two-factor authorization token
+
+        Returns:
+            A string tuple of JWT auth token and corresponding XRSF token.
+        """
+        url = f'{base_url.rstrip("/")}/tenant/oauth?tenant_id={tenant_id}'
+        form_data = {'grant_type': 'PASSWORD', 'username': username, 'password': password, 'tfa_token': tfa_token}
+        response = requests.post(url=url, data=form_data, timeout=60.0)
+        if response.status_code == 401:
+            message = response.json()['message'] if response.json() and 'message' in response.json() else None
+            # 1st request might fail due to missing TFA code
+            if any(x in response.json()['message'] for x in ['TOTP', 'TFA']):
+                raise MissingTfaError(cls.METHOD_POST, response.url, message)
+            raise UnauthorizedError(cls.METHOD_POST, response.url, message)
+        if response.status_code != 200:
+            message = response.json()['message'] if 'message' in response.json() else "Invalid request!"
+            raise HttpError(cls.METHOD_POST, response.url, response.status_code, message)
+        return response.cookies['authorization'], response.cookies['XSRF-TOKEN']
 
     def _create_session(self) -> requests.Session:
         s = requests.Session()
@@ -136,10 +176,8 @@ def prepare_request(self, method: str, resource: str,
         Returns:
             A PreparedRequest instance
         """
-        hs = self.__default_headers
-        if additional_headers:
-            hs.update(additional_headers)
-        rq = requests.Request(method=method, url=self.base_url + resource, headers=hs, auth=self.auth)
+        headers = {**(self.session.headers or {}), **(additional_headers or {})}
+        rq = requests.Request(method=method, url=self.base_url + resource, headers=headers, auth=self.auth)
         if json:
             rq.json = json
         return rq.prepare()

c8y_api/_main_api.py

@@ -3,6 +3,7 @@
 # and/or its subsidiaries and/or its affiliates and/or their licensors.
 # Use, reproduction, transfer, publication or disclosure is prohibited except
 # as specifically provided for in your License Agreement with Software AG.
+import contextlib
 
 from requests.auth import AuthBase
 
@@ -23,7 +24,7 @@
 from c8y_api.model.tenants import Tenants
 
 
-class CumulocityApi(CumulocityRestApi):
+class CumulocityApi(CumulocityRestApi, contextlib.AbstractContextManager):
     """Main Cumulocity API.
 
     Provides usage centric access to a Cumulocity instance.
@@ -35,7 +36,6 @@ def __init__(
             tenant_id: str,
             username: str = None,
             password: str = None,
-            tfa_token: str = None,
             auth: AuthBase = None,
             application_key: str = None,
             processing_mode: str = None,
@@ -45,7 +45,6 @@ def __init__(
             tenant_id,
             username=username,
             password=password,
-            tfa_token=tfa_token,
             auth=auth,
             application_key=application_key,
             processing_mode=processing_mode,
@@ -169,3 +168,9 @@ def audit_records(self) -> AuditRecords:
     def tenants(self) -> Tenants:
         """Provide access to the Audit API."""
         return self.__tenants
+
+    def __enter__(self) -> 'CumulocityApi':
+        return self
+
+    def __exit__(self, __exc_type, __exc_value, __traceback):
+        pass

c8y_api/_util.py

@@ -16,3 +16,18 @@ def c8y_keys() -> Set[str]:
     Returns: A set of environment variable names, starting with 'C8Y_'
     """
     return set(filter(lambda x: 'C8Y_' in x, os.environ.keys()))
+
+
+def validate_base_url(url) -> str:
+    """Ensure that a given url is a proper Cumulocity base url.
+
+    Args:
+        url (str):  A URL string with or without scheme, port, path
+
+    Returns:
+        A URL string with scheme (default is https) and port but
+        without trailing slash or even path.
+    """
+    i = url.find('://')  # scheme separator
+    j = url.find('/', i + 3)  # path separator
+    return ('https://' if i == -1 else '') + (url if j == -1 else url[:j])

c8y_api/app/__init__.py

@@ -179,6 +179,9 @@ def _build_user_instance(self, auth) -> CumulocityApi:
         return CumulocityApi(base_url=self.base_url, tenant_id=self.tenant_id, auth=auth,
                              application_key=self.application_key, processing_mode=self.processing_mode)
 
+    def __enter__(self) -> SimpleCumulocityApp:
+        return self
+
 
 class MultiTenantCumulocityApp(_CumulocityAppBase):
     """Multi-tenant enabled Cumulocity application wrapper.
@@ -337,3 +340,9 @@ def _get_tenant_instance(self, tenant_id: str) -> CumulocityApi:
             instance = self._create_tenant_instance(tenant_id)
             self._tenant_instances[tenant_id] = instance
             return instance
+
+    def __enter__(self) -> MultiTenantCumulocityApp:
+        return self
+
+    def __exit__(self, __exc_type, __exc_value, __traceback):
+        pass

c8y_api/model/_base.py

@@ -7,15 +7,13 @@
 from __future__ import annotations
 
 import logging
-from urllib.parse import quote_plus
 from typing import Any, Iterable, Set
+from urllib.parse import quote_plus, urlencode
 
 from collections.abc import MutableMapping
 from deprecated import deprecated
-from urllib.parse import urlencode
 
 from c8y_api._base_api import CumulocityRestApi
-
 from c8y_api.model._util import _DateUtil, _StringUtil, _QueryUtil
 
 
@@ -402,6 +400,29 @@ def __iadd__(self, other):
     def __contains__(self, name):
         return name in self.fragments
 
+    def get(self, path: str, default=None):
+        """Get a fragment/value by path.
+
+        Args:
+            path (str): A fragment/value path in dot notation, e.g.
+                "c8y_Firmware.version"
+            default: Sensible default if the path is not defined.
+
+        Returns:
+            The fragment/value specified via the path or the default value
+            if the path is not defined.
+        """
+        segments = path.split('.')
+        value = self
+        for segment in segments:
+            if segment in value:
+                value = value[segment]
+                continue
+            if hasattr(value, segment):
+                return value.__getattribute__(segment)
+            return default
+        return value
+
     @deprecated
     def set_attribute(self, name, value):
         # pylint: disable=missing-function-docstring
@@ -475,7 +496,6 @@ def build_object_path(self, object_id: int | str) -> str:
         """
         return self.resource + '/' + str(object_id)
 
-
     @staticmethod
     def _map_params(
             q=None,

c8y_api/model/inventory.py

@@ -8,7 +8,6 @@
 from __future__ import annotations
 
 from typing import Any, Generator, List
-from urllib.parse import urlencode, quote_plus
 
 from c8y_api.model._base import CumulocityResource
 from c8y_api.model._util import _QueryUtil

c8y_api/model/measurements.py

@@ -9,7 +9,6 @@
 import dataclasses
 from datetime import datetime, timedelta
 from typing import Type, List, Generator, Sequence
-from urllib.parse import urlencode, quote_plus
 
 from c8y_api._base_api import CumulocityRestApi
 

c8y_tk/interactive/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2020 Software AG,
+# Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA,
+# and/or its subsidiaries and/or its affiliates and/or their licensors.
+# Use, reproduction, transfer, publication or disclosure is prohibited except
+# as specifically provided for in your License Agreement with Software AG.
+
+
+from c8y_tk.interactive.context import *
+
+__all__ = ['CumulocityContext']