PLAT-10460: Implemented OBO-enabled endpoints (#123)

* Implemented OBO-enabled endpoints

* Renamed exception classes with Error suffix as advised by PEP-8

Author: symphony-elias

docs/authentication.md

@@ -0,0 +1,107 @@
+# Authentication
+The Symphony BDK authentication API allows developers to authenticate their bots and apps using RSA authentication mode.
+Please mind we only support RSA authentication.
+
+The following sections will explain you:
+- how to authenticate your bot service account
+- how to authenticate your app to use OBO (On Behalf Of) authentication
+
+## Bot authentication
+In this section we will see how to authenticate a bot service account using RSA authentication.
+
+> Read more about RSA authentication [here](https://developers.symphony.com/symphony-developer/docs/rsa-bot-authentication-workflow)
+
+Required `config.yaml` setup:
+```yaml
+host: acme.symphony.com
+bot:
+    username: bot-username
+    privateKey:
+      path: /path/to/rsa/private-key.pem
+```
+
+### Bot authentication deep-dive
+The code snippet below explains how to manually retrieve your bot authentication session. However, note that by default
+those operations are done behind the scene through the `SymphonyBdk` entry point.
+
+```python
+import logging
+
+from symphony.bdk.core.config.loader import BdkConfigLoader
+from symphony.bdk.core.symphony_bdk import SymphonyBdk
+
+async def run():
+    config = BdkConfigLoader.load_from_symphony_dir("config.yaml")
+    async with SymphonyBdk(config) as bdk:
+        auth_session = bdk.bot_session()
+        logging.info(await auth_session.key_manager_token)
+        logging.info(await auth_session.session_token)
+```
+
+### Multiple bot instances
+By design, the `SymphonyBdk` object contains a single bot session. However, you might want to create an application that
+has to handle multiple bot sessions, potentially using different authentication modes. This is possible by creating
+multiple instances of `SymphonyBdk` using different configurations:
+```python
+from symphony.bdk.core.config.loader import BdkConfigLoader
+from symphony.bdk.core.symphony_bdk import SymphonyBdk
+
+async def run():
+    config_a = BdkConfigLoader.load_from_symphony_dir("config_a.yaml")
+    config_b = BdkConfigLoader.load_from_symphony_dir("config_b.yaml")
+
+    async with SymphonyBdk(config_a) as bdk_a, SymphonyBdk(config_b) as bdk_b:
+        # use your two service accounts
+```
+
+## App authentication
+Application authentication is completely optional but remains required if you want to use OBO.
+
+Required `config.yaml` setup:
+```yaml
+host: acme.symphony.com
+app:
+    appId: app-id
+    privateKey:
+      path: /path/to/rsa/private-key.pem
+```
+
+### OBO (On Behalf Of) authentication
+> Read more about OBO authentication [here](https://developers.symphony.com/symphony-developer/docs/obo-overview)
+
+The following example shows how to retrieve OBO sessions using `username` (type `str`) or `user_id` (type `int`)
+and to call services which have OBO endpoints (users, streams, connections and messages so far):
+
+```python
+from symphony.bdk.core.config.loader import BdkConfigLoader
+from symphony.bdk.core.symphony_bdk import SymphonyBdk
+
+
+async def run():
+    config = BdkConfigLoader.load_from_symphony_dir("config.yaml")
+    async with SymphonyBdk(config) as bdk:
+        obo_auth_session = bdk.obo(username="username")
+        async with bdk.obo_services(obo_auth_session) as obo_services:
+            obo_services.messages().send_message("stream_id", "<messageML>Hello on behalf of user!</messageML>")
+```
+
+### BDK running without Bot username (service account) configured
+
+When the bot `username` (service account) is not configured in the Bdk configuration, the bot project will be still
+runnable but only in the OBO mode if the app authentication is well-configured.
+
+The `config.yaml` requires at least the application configuration:
+
+```yaml
+host: acme.symphony.com
+app:
+    appId: app-id
+    privateKey:
+      path: /path/to/private-key.pem
+```
+
+If users still try to access to Bdk services directly from `SymphonyBdk` facade object, a `BotNotConfiguredError`
+will be thrown.
+
+The example in [part above](#obo-on-behalf-of-authentication) shows how a bot project works without bot `username`
+configured.

symphony/bdk/core/auth/auth_session.py

@@ -1,4 +1,4 @@
-from symphony.bdk.core.auth.exception import AuthInitializationException
+from symphony.bdk.core.auth.exception import AuthInitializationError
 
 
 class AuthSession:
@@ -73,10 +73,10 @@ def __init__(self, authenticator, user_id: int = None, username: str = None):
         """
         super().__init__(authenticator)
         if user_id is not None and username is not None:
-            raise AuthInitializationException('Username and user id for OBO authentication should not be defined at '
+            raise AuthInitializationError('Username and user id for OBO authentication should not be defined at '
                                               'a same time.')
         if user_id is None and username is None:
-            raise AuthInitializationException('At least username or user id should be defined for '
+            raise AuthInitializationError('At least username or user id should be defined for '
                                               'OBO authentication.')
         self.user_id = user_id
         self.username = username
@@ -97,4 +97,4 @@ async def session_token(self):
 
     @property
     async def key_manager_token(self):
-        return None
+        return ""

symphony/bdk/core/auth/authenticator_factory.py

@@ -1,5 +1,5 @@
 from symphony.bdk.core.auth.bot_authenticator import BotAuthenticator, BotAuthenticatorRsa
-from symphony.bdk.core.auth.exception import AuthInitializationException
+from symphony.bdk.core.auth.exception import AuthInitializationError
 from symphony.bdk.core.auth.obo_authenticator import OboAuthenticator, OboAuthenticatorRsa
 from symphony.bdk.core.client.api_client_factory import ApiClientFactory
 from symphony.bdk.core.config.model.bdk_config import BdkConfig
@@ -28,13 +28,13 @@ def get_bot_authenticator(self) -> BotAuthenticator:
 
         :return: a new BotAuthenticator instance.
         """
-        if self._config.bot.is_rsa_authentication_configured() and self._config.bot.is_rsa_configuration_valid():
+        if self._config.bot.is_rsa_configuration_valid():
             return BotAuthenticatorRsa(
                 bot_config=self._config.bot,
                 login_api_client=self._api_client_factory.get_login_client(),
                 relay_api_client=self._api_client_factory.get_relay_client()
             )
-        raise AuthInitializationException("RSA authentication should be configured. Only one field among private key "
+        raise AuthInitializationError("RSA authentication should be configured. Only one field among private key "
                                           "path or content should be configured for bot authentication.")
 
     def get_obo_authenticator(self) -> OboAuthenticator:
@@ -47,5 +47,5 @@ def get_obo_authenticator(self) -> OboAuthenticator:
                 app_config=self._config.app,
                 login_api_client=self._api_client_factory.get_login_client()
             )
-        raise AuthInitializationException("Only one of private key path or content should be configured for "
+        raise AuthInitializationError("Only one of private key path or content should be configured for "
                                           "extension app authentication.")

symphony/bdk/core/auth/bot_authenticator.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 
 from symphony.bdk.core.auth.auth_session import AuthSession
-from symphony.bdk.core.auth.exception import AuthUnauthorizedException
+from symphony.bdk.core.auth.exception import AuthUnauthorizedError
 from symphony.bdk.core.auth.jwt_helper import create_signed_jwt
 from symphony.bdk.core.config.model.bdk_bot_config import BdkBotConfig
 from symphony.bdk.gen.api_client import ApiClient
@@ -28,15 +28,20 @@ async def authenticate_bot(self) -> AuthSession:
         :return: the authentication session.
         :rtype: AuthSession
         """
-        pass
 
     @abstractmethod
     async def retrieve_session_token(self):
-        pass
+        """Authenticates and retrieves a new session token.
+
+        :return: the retrieved session token.
+        """
 
     @abstractmethod
     async def retrieve_key_manager_token(self):
-        pass
+        """Authenticated and retrieved a new key manager session.
+
+        :return: the retrieved key manager session.
+        """
 
 
 class BotAuthenticatorRsa(BotAuthenticator):
@@ -65,7 +70,7 @@ async def _authenticate_and_get_token(self, api_client: ApiClient) -> str:
             token = await AuthenticationApi(api_client).pubkey_authenticate_post(req)
             return token.token
         except ApiException as e:
-            raise AuthUnauthorizedException(unauthorized_message, e)
+            raise AuthUnauthorizedError(unauthorized_message, e)
 
     async def retrieve_session_token(self) -> str:
         """Make the api call to the pod to get the pod's session token.

symphony/bdk/core/auth/exception.py

@@ -2,15 +2,15 @@
 """
 
 
-class AuthInitializationException(Exception):
+class AuthInitializationError(Exception):
     """Thrown when unable to read/parse a RSA Private Key or a certificate.
     """
 
     def __init__(self, message: str):
         self.message = message
 
 
-class AuthUnauthorizedException(Exception):
+class AuthUnauthorizedError(Exception):
     """When thrown, it means that authentication cannot be performed for several reasons
     """
 

symphony/bdk/core/auth/obo_authenticator.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 
 from symphony.bdk.core.auth.auth_session import OboAuthSession
-from symphony.bdk.core.auth.exception import AuthUnauthorizedException
+from symphony.bdk.core.auth.exception import AuthUnauthorizedError
 from symphony.bdk.core.auth.jwt_helper import create_signed_jwt
 from symphony.bdk.core.config.model.bdk_app_config import BdkAppConfig
 from symphony.bdk.gen.api_client import ApiClient
@@ -44,7 +44,6 @@ async def retrieve_obo_session_token_by_user_id(
         :return: The obo session token.
 
         """
-        pass
 
     @abstractmethod
     async def retrieve_obo_session_token_by_username(
@@ -59,7 +58,6 @@ async def retrieve_obo_session_token_by_username(
         :return: The obo session token.
 
         """
-        pass
 
     def authenticate_by_username(self, username: str):
         """Authenticate On-Behalf-Of user by username.
@@ -97,7 +95,7 @@ async def _authenticate_and_retrieve_app_session_token(self):
             token = await self._authentication_api.pubkey_app_authenticate_post(req)
             return token.token
         except ApiException:
-            raise AuthUnauthorizedException(self.unauthorized_message)
+            raise AuthUnauthorizedError(self.unauthorized_message)
 
     async def _authenticate_and_retrieve_obo_session_token(
             self,
@@ -118,7 +116,7 @@ async def _authenticate_and_retrieve_obo_session_token(
                 token = await self._authentication_api.pubkey_app_username_username_authenticate_post(**params)
                 return token.token
         except ApiException:
-            raise AuthUnauthorizedException(self.unauthorized_message)
+            raise AuthUnauthorizedError(self.unauthorized_message)
 
     async def retrieve_obo_session_token_by_user_id(self, user_id: int):
         """

symphony/bdk/core/config/exception.py

@@ -2,12 +2,12 @@
 """
 
 
-class BdkConfigException(Exception):
+class BdkConfigError(Exception):
     """Exception class raised when configuration is invalid.
     """
 
 
-class BotNotConfiguredException(Exception):
+class BotNotConfiguredError(Exception):
     """Thrown when the bot configuration is not specified."""
 
     def __init__(self, message="Bot (service account) credentials have not been configured."):

symphony/bdk/core/config/loader.py

@@ -3,7 +3,7 @@
 
 import yaml
 
-from symphony.bdk.core.config.exception import BdkConfigException
+from symphony.bdk.core.config.exception import BdkConfigError
 from symphony.bdk.core.config.model.bdk_config import BdkConfig
 
 
@@ -26,7 +26,7 @@ def load_from_file(cls, config_path: str) -> BdkConfig:
         if config_path.exists():
             config_content = config_path.read_text()
             return cls.load_from_content(config_content)
-        raise BdkConfigException(f"Config file has not been found at: {config_path.absolute()}")
+        raise BdkConfigError(f"Config file has not been found at: {config_path.absolute()}")
 
     @classmethod
     def load_from_content(cls, content: str) -> BdkConfig:
@@ -77,4 +77,4 @@ def parse(cls, config_content: str):
         except yaml.YAMLError:
             pass
 
-        raise BdkConfigException("Config file is neither in JSON nor in YAML format.")
+        raise BdkConfigError("Config file is neither in JSON nor in YAML format.")

symphony/bdk/core/service/connection/connection_service.py

@@ -5,16 +5,16 @@
 from symphony.bdk.gen.pod_model.user_connection_request import UserConnectionRequest
 
 
-class ConnectionService:
-    """Service class for managing the connections between users
+class OboConnectionService:
+    """Class exposing OBO-enabled endpoints for connection management.
 
-    This service is used for retrieving the connection status if the calling user with a specified user or with many
+    This service is used for retrieving the connection status between the OBO user and a specified user or several
     other internal or external users in the pod, and perform some actions related to the connection status like:
 
     * Send a connection request to an user
-    * Accept a connection request from an user
-    * Reject a connection request from an user
-    * Remove a connection with an user
+    * Accept a connection request from a user
+    * Reject a connection request from a user
+    * Remove a connection with a user
     """
 
     def __init__(self, connection_api: ConnectionApi, auth_session: AuthSession):
@@ -131,3 +131,16 @@ async def remove_connection(self, user_id: int) -> None:
             'session_token': await self._auth_session.session_token
         }
         await self._connection_api.v1_connection_user_uid_remove_post(**params)
+
+
+class ConnectionService(OboConnectionService):
+    """Service class for managing the connections between users
+
+    This service is used for retrieving the connection status between the calling user and a specified user or several
+    other internal or external users in the pod, and perform some actions related to the connection status like:
+
+    * Send a connection request to an user
+    * Accept a connection request from a user
+    * Reject a connection request from a user
+    * Remove a connection with a user
+    """

symphony/bdk/core/service/datafeed/on_disk_datafeed_id_repository.py

@@ -6,6 +6,7 @@
 
 logger = logging.getLogger(__name__)
 
+
 class DatafeedIdRepository(ABC):
     """A repository interface for storing a datafeed id.
     By using the DatafeedLoopV1, the created datafeed id and agent base url has to be persisted on the BDK side.