catalystwan 0.34.0.dev3__tar.gz → 0.34.0.dev4__tar.gz

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: catalystwan
-Version: 0.34.0.dev3
+Version: 0.34.0.dev4
 Summary: Cisco Catalyst WAN SDK for Python
 Home-page: https://github.com/cisco-open/cisco-catalyst-wan-sdk
 Author: kagorski
@@ -66,6 +66,7 @@ with create_manager_session(url=url, username=username, password=password) as se
     devices = session.api.devices.get()
     print(devices)
 ```
+
 **ManagerSession** extends [requests.Session](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects) so all functionality from [requests](https://requests.readthedocs.io/en/latest/) library is avaiable to user, it also implements python [contextmanager](https://docs.python.org/3.8/library/contextlib.html#contextlib.contextmanager) and automatically frees server resources on exit.
 
 <details>
@@ -75,13 +76,15 @@ It is possible to configure **ManagerSession** prior sending any request.
 
 ```python
 from catalystwan.session import ManagerSession
+from catalystwan.vmanage_auth import vManageAuth
 
 url = "example.com"
 username = "admin"
 password = "password123"
 
 # configure session using constructor - nothing will be sent to target server yet
-session = ManagerSession(url=url, username=username, password=password)
+auth = vManageAuth(username, password)
+session = ManagerSession(url=url, auth=auth)
 # login and send requests
 session.login()
 session.get("/dataservice/device")
@@ -130,6 +133,25 @@ with create_manager_session(url=url, username=username, password=password, subdo
 
 </details>
 
+<details>
+    <summary> <b>Login using Api Gateway</b> <i>(click to expand)</i></summary>
+
+```python
+from catalystwan.session import create_apigw_session
+
+with create_apigw_session(
+    url="example.com",
+    client_id="client_id",
+    client_secret="client_secret",
+    org_name="Org-Name",
+    username="user",
+    mode="user",
+    token_duration=10,
+) as session:
+    devices = session.api.devices.get()
+    print(devices)
+```
+</details>
 
 
 ## API usage examples

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/README.md

@@ -38,6 +38,7 @@ with create_manager_session(url=url, username=username, password=password) as se
     devices = session.api.devices.get()
     print(devices)
 ```
+
 **ManagerSession** extends [requests.Session](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects) so all functionality from [requests](https://requests.readthedocs.io/en/latest/) library is avaiable to user, it also implements python [contextmanager](https://docs.python.org/3.8/library/contextlib.html#contextlib.contextmanager) and automatically frees server resources on exit.
 
 <details>
@@ -47,13 +48,15 @@ It is possible to configure **ManagerSession** prior sending any request.
 
 ```python
 from catalystwan.session import ManagerSession
+from catalystwan.vmanage_auth import vManageAuth
 
 url = "example.com"
 username = "admin"
 password = "password123"
 
 # configure session using constructor - nothing will be sent to target server yet
-session = ManagerSession(url=url, username=username, password=password)
+auth = vManageAuth(username, password)
+session = ManagerSession(url=url, auth=auth)
 # login and send requests
 session.login()
 session.get("/dataservice/device")
@@ -102,6 +105,25 @@ with create_manager_session(url=url, username=username, password=password, subdo
 
 </details>
 
+<details>
+    <summary> <b>Login using Api Gateway</b> <i>(click to expand)</i></summary>
+
+```python
+from catalystwan.session import create_apigw_session
+
+with create_apigw_session(
+    url="example.com",
+    client_id="client_id",
+    client_secret="client_secret",
+    org_name="Org-Name",
+    username="user",
+    mode="user",
+    token_duration=10,
+) as session:
+    devices = session.api.devices.get()
+    print(devices)
+```
+</details>
 
 
 ## API usage examples

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/catalystwan/api/administration.py

@@ -101,7 +101,7 @@ class UsersAPI:
         """
         self._endpoints.update_user(user_update_request.username, user_update_request)
 
-    def update_password(self, username: str, new_password: str):
+    def update_password(self, username: str, new_password: str, current_user_password: str):
         """Updates exisiting user password
 
         Args:
@@ -109,8 +109,8 @@ class UsersAPI:
             new_password (str): New password for given user
         """
         update_password_request = UserUpdateRequest(
-            username=username, password=new_password, current_user_password=self.session.password
-        )  # type: ignore
+            username=username, password=new_password, current_user_password=current_user_password
+        )
         self._endpoints.update_password(username, update_password_request)
 
     def reset(self, username: str):

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/catalystwan/api/tenant_management_api.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, List
 
 from catalystwan.api.task_status_api import Task
 from catalystwan.endpoints.tenant_management import (
@@ -62,7 +62,7 @@ class TenantManagementAPI:
             tenant_id=tenant_update_request.tenant_id, tenant_update_request=tenant_update_request
         )
 
-    def delete(self, tenant_id_list: List[str], password: Optional[str] = None) -> Task:
+    def delete(self, tenant_id_list: List[str], password: str) -> Task:
         """Deletes tenants on vManage
 
         Args:
@@ -72,8 +72,6 @@ class TenantManagementAPI:
         Returns:
             Task: Object representing tenant deletion process
         """
-        if password is None:
-            password = self.session.password
         delete_request = TenantBulkDeleteRequest(tenant_id_list=tenant_id_list, password=password)
         task_id = self._endpoints.delete_tenant_async_bulk(delete_request).id
         return Task(self.session, task_id)

catalystwan-0.34.0.dev4/catalystwan/apigw_auth.py

@@ -0,0 +1,81 @@
+import logging
+from typing import TYPE_CHECKING, Literal, Optional
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, Field, PositiveInt
+from requests import PreparedRequest, post
+from requests.auth import AuthBase
+
+from catalystwan.exceptions import CatalystwanException
+from catalystwan.response import ManagerResponse
+
+if TYPE_CHECKING:
+    from catalystwan.session import ManagerSession
+
+LoginMode = Literal["machine", "user", "session"]
+
+
+class ApiGwLogin(BaseModel):
+    client_id: str
+    client_secret: str
+    org_name: str
+    mode: Optional[LoginMode] = None
+    username: Optional[str] = None
+    session: Optional[str] = None
+    tenant_user: Optional[bool] = None
+    token_duration: PositiveInt = Field(default=10, description="in minutes")
+
+
+class ApiGwAuth(AuthBase):
+    """Attaches ApiGateway Authentication to the given Requests object.
+
+    1. Get a bearer token by sending a POST request to the /apigw/login endpoint.
+    2. Use the token in the Authorization header for subsequent requests.
+    """
+
+    def __init__(self, login: ApiGwLogin, logger: Optional[logging.Logger] = None):
+        self.login = login
+        self.token = ""
+        self.logger = logger or logging.getLogger(__name__)
+
+    def __call__(self, request: PreparedRequest) -> PreparedRequest:
+        self.handle_auth(request)
+        self.build_digest_header(request)
+        return request
+
+    def handle_auth(self, request: PreparedRequest) -> None:
+        if self.token == "":
+            self.authenticate(request)
+
+    def authenticate(self, request: PreparedRequest):
+        base_url = f"{str(urlparse(request.url).scheme)}://{str(urlparse(request.url).netloc)}"
+        self.token = self.get_token(base_url, self.login)
+
+    def build_digest_header(self, request: PreparedRequest) -> None:
+        header = {
+            "sdwan-org": self.login.org_name,
+            "Authorization": f"Bearer {self.token}",
+        }
+        request.headers.update(header)
+
+    @staticmethod
+    def get_token(base_url: str, apigw_login: ApiGwLogin) -> str:
+        response = post(
+            url=f"{base_url}/apigw/login",
+            verify=False,
+            json=apigw_login.model_dump(exclude_none=True),
+            timeout=10,
+        )
+        token = response.json().get("token", "")
+        if not token or not isinstance(token, str):
+            raise CatalystwanException("Failed to get bearer token")
+        return token
+
+    def __str__(self) -> str:
+        return f"ApiGatewayAuth(mode={self.login.mode})"
+
+    def logout(self, session: "ManagerSession") -> Optional[ManagerResponse]:
+        return None
+
+    def clear_tokens_and_cookies(self) -> None:
+        self.token = ""

catalystwan-0.34.0.dev4/catalystwan/endpoints/api_gateway.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+
+from catalystwan.endpoints import APIEndpoints, post
+
+
+class OnBoardClient(BaseModel):
+    client_id: str
+    client_secret: str
+    client_name: str
+
+
+class ApiGateway(APIEndpoints):
+    @post("/apigw/config/reload")
+    def configuration_reload(self) -> None:
+        """After launching the API Gateway, SSP can use the API
+        and bearer authentication header with provision access token obtained
+        in the step above. It reloads the configuration from S3 bucket, Secrets Manager
+        and reset the RDS connection pool."""
+        ...
+
+    @post("/apigw/client/registration")
+    def on_board_client(self, payload: OnBoardClient) -> None:
+        ...

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/catalystwan/integration_tests/base.py

@@ -45,7 +45,6 @@ def create_session() -> ManagerSession:
     """Try to create a session with the environment variables, if it fails, raise an exception"""
     try:
         session = create_manager_session(**load_config())
-        session.is_for_testing = True
         return session
     except Exception:
         raise CatalystwanException("Failed to create session")

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/catalystwan/response.py

@@ -139,6 +139,7 @@ class ManagerResponse(Response, APIEndpointClientResponse):
     def __init__(self, response: Response):
         self.__dict__.update(response.__dict__)
         self.jsessionid_expired = self._detect_expired_jsessionid()
+        self.api_gw_unauthorized = self._detect_apigw_unauthorized()
         try:
             self.payload = JsonPayload(response.json())
         except JSONDecodeError:
@@ -163,6 +164,10 @@ class ManagerResponse(Response, APIEndpointClientResponse):
         jar.update(parse_cookies_to_dict(cookies_string))
         return jar
 
+    def _detect_apigw_unauthorized(self) -> bool:
+        """Determines if server sent unauthorized response"""
+        return self.status_code == 401 and self.json().get("message", "") == "failed to validate user"
+
     def info(self, history: bool = False) -> str:
         """Returns human readable string containing Request-Response contents
         Args:

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/catalystwan/session.py

@@ -7,15 +7,15 @@ from enum import Enum
 from functools import cached_property
 from pathlib import Path
 from time import monotonic, sleep
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
 from urllib.parse import urljoin, urlparse, urlunparse
 
 from packaging.version import Version  # type: ignore
 from requests import PreparedRequest, Request, Response, Session, get, head
-from requests.auth import AuthBase
 from requests.exceptions import ConnectionError, HTTPError, RequestException
 
 from catalystwan import USER_AGENT
+from catalystwan.apigw_auth import ApiGwAuth, ApiGwLogin, LoginMode
 from catalystwan.endpoints import APIEndpointClient
 from catalystwan.endpoints.client import AboutInfo, ServerInfo
 from catalystwan.exceptions import (
@@ -80,6 +80,73 @@ def determine_session_type(
         return SessionType.NOT_DEFINED
 
 
+def create_base_url(url: str, port: Optional[int] = None) -> str:
+    """Creates base url based on ip address or domain and port if provided.
+
+    Returns:
+        str: Base url shared for every request.
+    """
+    parsed_url = urlparse(url)
+    netloc: str = parsed_url.netloc or parsed_url.path
+    scheme: str = parsed_url.scheme or "https"
+    base_url = urlunparse((scheme, netloc, "", None, None, None))
+    if port:
+        return f"{base_url}:{port}"  # noqa: E231
+    return base_url
+
+
+def create_apigw_session(
+    url: str,
+    client_id: str,
+    client_secret: str,
+    org_name: str,
+    subdomain: Optional[str] = None,
+    port: Optional[int] = None,
+    mode: Optional[LoginMode] = None,
+    username: Optional[str] = None,
+    session: Optional[str] = None,
+    tenant_user: Optional[bool] = None,
+    token_duration: int = 10,
+    logger: Optional[logging.Logger] = None,
+) -> ManagerSession:
+    """Factory method that creates session object and performs login according to parameters
+
+    Args:
+        url (str): IP address or domain name
+        client_id (str): client id
+        client_secret (str): client secret
+        org_name (str): organization name
+        subdomain: subdomain specifying to which view switch when creating provider as a tenant session,
+            works only on provider user mode
+        port (int): port
+        mode (LoginMode): login mode
+        username (str): username
+        session (str): session
+        tenant_user (bool): tenant user
+        token_duration (int): token duration
+        logger: override default module logger
+
+    Returns:
+        ManagerSession: logged-in and operative session to perform tasks on SDWAN Manager.
+    """
+    auth = ApiGwAuth(
+        login=ApiGwLogin(
+            client_id=client_id,
+            client_secret=client_secret,
+            org_name=org_name,
+            mode=mode,
+            username=username,
+            session=session,
+            tenant_user=tenant_user,
+            token_duration=token_duration,
+        ),
+        logger=logger,
+    )
+    session_ = ManagerSession(base_url=create_base_url(url, port), auth=auth, subdomain=subdomain, logger=logger)
+    session_.state = ManagerSessionState.LOGIN
+    return session_
+
+
 def create_manager_session(
     url: str,
     username: str,
@@ -102,13 +169,14 @@ def create_manager_session(
     Returns:
         ManagerSession: logged-in and operative session to perform tasks on SDWAN Manager.
     """
-    session = ManagerSession(url=url, username=username, password=password, port=port, subdomain=subdomain)
-
-    if logger:
-        session.logger = logger
-
+    auth = vManageAuth(username, password, logger=logger)
+    session = ManagerSession(
+        base_url=create_base_url(url, port),
+        auth=auth,
+        subdomain=subdomain,
+        logger=logger,
+    )
     session.state = ManagerSessionState.LOGIN
-    session.on_session_create_hook()
     return session
 
 
@@ -135,53 +203,55 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
     Defines methods and handles session connectivity available for provider, provider as tenant, and tenant.
 
     Args:
-        url: IP address or domain name, i.e. '10.0.1.200' or 'example.com'
-        port: port
-        username: username
-        password: password
+        base_url: IP address or domain name, i.e. '10.0.1.200' or 'example.com'
+        auth: authentication object - vManage or API Gateway
+        subdomain: subdomain specifying to which view switch when creating provider as a tenant session,
+            works only on provider user mode
+        logger: override default module logger
 
     Attributes:
         enable_relogin (bool): defaults to True, in case that session is not properly logged-in, session will try to
             relogin and try the same request again
-    """
+        api: APIContainer: container for API methods
+        endpoints: APIEndpointContainter: container for API endpoints
+        state: ManagerSessionState: current state of the session can be used to control session flow
+        response_trace: Callable: function that logs response and request details
+        server_name: str: server name
+        platform_version: str: platform version
+        api_version: Version: API version
+        restart_timeout: int: restart timeout in seconds
+        session_type: SessionType: type of session
+        verify: bool: verify SSL certificate
 
-    on_session_create_hook: ClassVar[Callable[[ManagerSession], Any]] = lambda *args: None
+    """
 
     def __init__(
         self,
-        url: str,
-        username: str,
-        password: str,
-        verify: bool = False,
-        port: Optional[int] = None,
+        base_url: str,
+        auth: Union[vManageAuth, ApiGwAuth],
         subdomain: Optional[str] = None,
-        auth: Optional[AuthBase] = None,
-        validate_responses: bool = True,
-    ):
-        self.url = url
-        self.port = port
-        self.base_url = self.__create_base_url()
-        self.username = username
-        self.password = password
+        logger: Optional[logging.Logger] = None,
+    ) -> None:
+        self.base_url = base_url
         self.subdomain = subdomain
         self._session_type = SessionType.NOT_DEFINED
         self.server_name: Optional[str] = None
-        self.logger = logging.getLogger(__name__)
+        self.logger = logger or logging.getLogger(__name__)
         self.enable_relogin: bool = True
         self.response_trace: Callable[
             [Optional[Response], Union[Request, PreparedRequest, None]], str
         ] = response_history_debug
         super(ManagerSession, self).__init__()
+        self.verify = False
         self.headers.update({"User-Agent": USER_AGENT})
-        self.__prepare_session(verify, auth)
+        self._auth = auth
         self._platform_version: str = ""
         self._api_version: Version = NullVersion  # type: ignore
-        self._state: ManagerSessionState = ManagerSessionState.OPERATIVE
         self.restart_timeout: int = 1200
         self.polling_requests_timeout: int = 10
         self.request_timeout: Optional[int] = None
-        self._validate_responses = validate_responses
-        self._is_for_testing = False
+        self._validate_responses = True
+        self._state: ManagerSessionState = ManagerSessionState.OPERATIVE
 
     @cached_property
     def api(self) -> APIContainer:
@@ -243,11 +313,9 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
         Returns:
             ManagerSession: (self)
         """
-
         self.cookies.clear_session_cookies()
-        self.auth = vManageAuth(self.base_url, self.username, self.password, verify=False)
-        self.auth.logger = self.logger
-
+        self._auth.clear_tokens_and_cookies()
+        self.auth = self._auth
         if self.subdomain:
             tenant_id = self.get_tenant_id()
             vsession_id = self.get_virtual_session_id(tenant_id)
@@ -276,12 +344,16 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
             )
 
         self.logger.info(
-            f"Logged to vManage({self.platform_version}) as {self.username}. The session type is {self.session_type}"
+            f"Logged to vManage({self.platform_version}) as {self.auth}. The session type is {self.session_type}"
         )
-        if jsessionid := self.auth.set_cookie.get("JSESSIONID"):
-            self.cookies.set("JSESSIONID", jsessionid)
+        self._set_jsessionid(self.auth)
         return self
 
+    def _set_jsessionid(self, auth: Union[vManageAuth, ApiGwAuth]) -> None:
+        if isinstance(auth, vManageAuth):
+            if jsessionid := auth.jsessionid:
+                self.cookies.set("JSESSIONID", jsessionid)
+
     def wait_server_ready(self, timeout: int, poll_period: int = 10) -> None:
         """Waits until server is ready for API requests with given timeout in seconds"""
 
@@ -357,6 +429,11 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
             self.state = ManagerSessionState.LOGIN
             return self.request(method, url, *args, **_kwargs)
 
+        if self.enable_relogin and response.api_gw_unauthorized and self.state == ManagerSessionState.OPERATIVE:
+            self.logger.warning("Logging to API GW session. Reason: unauthorized detected in response headers")
+            self.state = ManagerSessionState.LOGIN
+            return self.request(method, url, *args, **_kwargs)
+
         if response.request.url and "passwordReset.html" in response.request.url:
             raise DefaultPasswordError("Password must be changed to use this session.")
 
@@ -372,20 +449,6 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
         """Returns base API url plus given url path."""
         return urljoin(self.base_url, url_path)
 
-    def __create_base_url(self) -> str:
-        """Creates base url based on ip address or domain and port if provided.
-
-        Returns:
-            str: Base url shared for every request.
-        """
-        url = urlparse(self.url)
-        netloc: str = url.netloc or url.path
-        scheme: str = url.scheme or "https"
-        base_url = urlunparse((scheme, netloc, "", None, None, None))
-        if self.port:
-            return f"{base_url}:{self.port}"  # noqa: E231
-        return base_url
-
     def about(self) -> AboutInfo:
         return self.endpoints.client.about()
 
@@ -449,23 +512,7 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
         return response.json()["VSessionId"]
 
     def logout(self) -> Optional[ManagerResponse]:
-        response = None
-        if isinstance((version := self.api_version), NullVersion):
-            self.logger.warning("Cannot perform logout operation without known api_version.")
-            return response
-        else:
-            # disable automatic relogin before performing logout request
-            _relogin = self.enable_relogin
-            try:
-                self.enable_relogin = False
-                if version >= Version("20.12"):
-                    response = self.post("/logout")
-                else:
-                    response = self.get("/logout")
-            finally:
-                # restore original setting after performing logout request
-                self.enable_relogin = _relogin
-        return response
+        return self._auth.logout(self)
 
     def close(self) -> None:
         """Closes the ManagerSession.
@@ -481,10 +528,6 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
         self.logout()
         super().close()
 
-    def __prepare_session(self, verify: bool, auth: Optional[AuthBase]) -> None:
-        self.auth = auth
-        self.verify = verify
-
     @property
     def session_type(self) -> SessionType:
         return self._session_type
@@ -510,33 +553,8 @@ class ManagerSession(ManagerResponseAdapter, APIEndpointClient):
     def validate_responses(self, value: bool):
         self._validate_responses = value
 
-    @property
-    def is_for_testing(self) -> bool:
-        return self._is_for_testing
-
-    @is_for_testing.setter
-    def is_for_testing(self, value: bool):
-        self._is_for_testing = value
+    def __copy__(self) -> ManagerSession:
+        return ManagerSession(base_url=self.base_url, auth=self._auth, subdomain=self.subdomain, logger=self.logger)
 
     def __str__(self) -> str:
-        return f"{self.username}@{self.base_url}"
-
-    def __repr__(self):
-        if self._is_for_testing:
-            return f"{self.__class__.__name__}('TEST_SESSION')"
-        return (
-            f"{self.__class__.__name__}('{self.url}', '{self.username}', '{self.password}', port={self.port}, "
-            f"subdomain='{self.subdomain}')"
-        )
-
-    def __eq__(self, other):
-        if isinstance(other, ManagerSession):
-            comparison_list = [
-                self.url == other.url,
-                self.username == other.username,
-                self.password == other.password,
-                self.port == other.port,
-                str(self.subdomain) == str(other.subdomain),
-            ]
-            return True if all(comparison_list) else False
-        return False
+        return f"ManagerSession(session_type={self.session_type}, auth={self._auth})"

{catalystwan-0.34.0.dev3 → catalystwan-0.34.0.dev4}/catalystwan/tests/test_administration.py

@@ -122,13 +122,14 @@ class TestUsersAPI(unittest.TestCase):
         # Arrange
         username = "new_user"
         new_password = "PaSsWoRd"  # pragma: allowlist secret
+        current_password = "32313123213"  # pragma: allowlist secret
         self.api._endpoints.update_password = MagicMock()
         # Act
-        self.api.update_password(username, new_password)
+        self.api.update_password(username, new_password, current_password)
         # Assert
         self.api._endpoints.update_password.assert_called_once_with(
             username,
-            UserUpdateRequest(username=username, password=new_password, current_user_password=self.session.password),
+            UserUpdateRequest(username=username, password=new_password, current_user_password=current_password),
         )
 
     def test_reset(self):