pyxecm 1.4__py3-none-any.whl → 1.5__py3-none-any.whl

pyxecm/otac.py

@@ -8,10 +8,21 @@ __init__ : class initializer
 config : returns config data set
 hostname: returns the Archive Center hostname
 set_hostname: sets the Archive Center hostname
+credentials: Get credentials (username + password)
+set_credentials: Set the credentials for Archive Center for the "ds" and "admin" users
+base_url: Returns the Archive Center base URL
+exec_url: Returns the Archive Center URL to execute commands
+request_form_header: Deliver the FORM request header used for the SOAP calls.
+request_json_header: Deliver the JSON request header used for the CRUD REST API calls.
+parse_request_response: Converts the text property of a request response object to a 
+                        Python dict in a safe way that also handles exceptions.
+authenticate: Authenticates at Archive Center and retrieve Ticket
+authenticate_soap: Authenticate via SOAP with admin User
 exec_command: exec a command on Archive Center
 put_cert: put Certificate on Archive Center
-enable_cert: enables Certitificate on Archive Center
-
+enable_cert: enables Certitificate on Archive Center via SOAP
+enable_certificate: Enable a certificate via the new REST API
+                    (replacing the old SOAP interface)
 """
 
 __author__ = "Dr. Marc Diefenbruch"
@@ -23,6 +34,7 @@ __email__ = "mdiefenb@opentext.com"
 import logging
 import os
 import base64
+import json
 import requests
 
 from suds.client import Client
@@ -30,14 +42,21 @@ from suds import WebFault
 
 logger = logging.getLogger("pyxecm.otac")
 
-requestHeaders = {"Content-Type": "application/x-www-form-urlencoded"}
+REQUEST_FORM_HEADERS = {"Content-Type": "application/x-www-form-urlencoded"}
+
+REQUEST_JSON_HEADERS = {
+    "accept": "application/json;charset=utf-8",
+    "Content-Type": "application/json",
+}
 
+REQUEST_TIMEOUT = 60
 
 class OTAC:
     """Used to automate stettings in OpenText Archive Center."""
 
     _config = None
     _soap_token: str = ""
+    _otac_ticket = None
 
     def __init__(
         self,
@@ -48,6 +67,7 @@ class OTAC:
         ds_password: str,
         admin_username: str,
         admin_password: str,
+        otds_ticket: str | None = None,
     ):
         """Initialize the OTAC object
 
@@ -104,8 +124,12 @@ class OTAC:
         otac_exec_url = otac_base_url + "/archive/admin/exec"
         otac_config["execUrl"] = otac_exec_url
         otac_config["baseUrl"] = otac_base_url
+        otac_config["restUrl"] = otac_base_url + "/ot-admin/rest"
+        otac_config["certUrl"] = otac_config["restUrl"] + "/keystore/cert/status"
+        otac_config["authenticationUrl"] = otac_config["restUrl"] + "/auth/users/login"
 
         self._config = otac_config
+        self._otac_ticket = otds_ticket
 
     def config(self) -> dict:
         """Returns the configuration dictionary
@@ -131,6 +155,17 @@ class OTAC:
         """
         self.config()["hostname"] = hostname
 
+    def credentials(self) -> dict:
+        """Get credentials (username + password)
+
+        Returns:
+            dict: dictionary with username and password
+        """
+        return {
+            "username": self.config()["admin_username"],
+            "password": self.config()["admin_password"],
+        }
+
     def set_credentials(
         self,
         ds_username: str = "",
@@ -182,7 +217,162 @@ class OTAC:
         """
         return self.config()["execUrl"]
 
-    def _soap_login(self):
+    def request_form_header(self) -> dict:
+        """Deliver the FORM request header used for the SOAP calls.
+           Consists of Token + Form Headers (see global variable)
+
+        Args:
+            None.
+        Return:
+            dict: request header values
+        """
+
+        # create union of two dicts: cookie and headers
+        # (with Python 3.9 this would be easier with the "|" operator)
+        request_header = {}
+        request_header.update("token" + self._otac_ticket)
+        request_header.update(REQUEST_FORM_HEADERS)
+
+        return request_header
+
+    # end method definition
+
+    def request_json_header(self) -> dict:
+        """Deliver the JSON request header used for the CRUD REST API calls.
+           Consists of Cookie + JSON Headers (see global variable)
+
+        Args:
+            None.
+        Return:
+            dict: request header values
+        """
+
+        if not self._otac_ticket:
+            self.authenticate(revalidate=True)
+
+        # create union of two dicts: cookie and headers
+        # (with Python 3.9 this would be easier with the "|" operator)
+        request_header = {}
+        request_header["Authorization"] = "token " + self._otac_ticket
+        request_header.update(REQUEST_JSON_HEADERS)
+
+        return request_header
+
+    # end method definition
+
+    def parse_request_response(
+        self,
+        response_object: object,
+        additional_error_message: str = "",
+        show_error: bool = True,
+    ) -> dict | None:
+        """Converts the text property of a request response object to a
+           Python dict in a safe way that also handles exceptions.
+        Args:
+            response_object (object): this is reponse object delivered by the request call
+            additional_error_message (str): print a custom error message
+            show_error (bool): if True log an error, if False log a warning
+
+        Returns:
+            dict: response or None in case of an error
+        """
+
+        if not response_object:
+            return None
+
+        try:
+            dict_object = json.loads(response_object.text)
+        except json.JSONDecodeError as exception:
+            if additional_error_message:
+                message = "Cannot decode response as JSon. {}; error -> {}".format(
+                    additional_error_message, exception
+                )
+            else:
+                message = "Cannot decode response as JSon; error -> {}".format(
+                    exception
+                )
+            if show_error:
+                logger.error(message)
+            else:
+                logger.debug(message)
+            return None
+        else:
+            return dict_object
+
+    # end method definition
+
+    def authenticate(self, revalidate: bool = False) -> dict | None:
+        """Authenticates at Archive Center and retrieve Ticket.
+
+        Args:
+            revalidate (bool, optional): determinse if a re-athentication is enforced
+                                         (e.g. if session has timed out with 401 error)
+                                         By default we use the OTDS ticket (if exists) for the authentication with OTCS.
+                                         This switch allows the forced usage of username / password for the authentication.
+        Returns:
+            dict: Cookie information of None in case of an error.
+                  Also stores cookie information in self._cookie
+        """
+
+        # Already authenticated and session still valid?
+        if self._otac_ticket and not revalidate:
+            logger.debug(
+                "Session still valid - return existing ticket -> %s",
+                str(self._otac_ticket),
+            )
+            return self._otac_ticket
+
+        otac_ticket = None
+
+        request_url = self.config()["authenticationUrl"]
+        # Check if previous authentication was not successful.
+        # Then we do the normal username + password authentication:
+        logger.debug(
+            "Requesting OTAC ticket with User/Password; calling -> %s",
+            request_url,
+        )
+
+        response = None
+        try:
+            response = requests.post(
+                url=request_url,
+                data=json.dumps(
+                    self.credentials()
+                ),  # this includes username + password
+                headers=REQUEST_JSON_HEADERS,
+                timeout=REQUEST_TIMEOUT,
+            )
+        except requests.exceptions.RequestException as exception:
+            logger.warning(
+                "Unable to connect to -> %s; error -> %s",
+                request_url,
+                exception.strerror,
+            )
+            logger.warning("OTAC service may not be ready yet.")
+            return None
+
+        if response.ok:
+            authenticate_list = self.parse_request_response(
+                response, "This can be normal during restart", False
+            )
+            if not authenticate_list:
+                return None
+            else:
+                authenticate_dict = authenticate_list[1]
+                otac_ticket = authenticate_dict["TOKEN"]
+                logger.debug("Ticket -> %s", otac_ticket)
+        else:
+            logger.error("Failed to request an OTAC ticket; error -> %s", response.text)
+            return None
+
+        # Store authentication ticket:
+        self._otac_ticket = otac_ticket
+
+        return self._otac_ticket
+
+    # end method definition
+
+    def authenticate_soap(self) -> str:
         """Authenticate via SOAP with admin User
 
         Args:
@@ -202,13 +392,13 @@ class OTAC:
 
     # end method definition
 
-    def exec_command(self, command: str):
+    def exec_command(self, command: str) -> dict:
         """Execute a command on Archive Center
 
         Args:
             command (str): command to execute
         Returns:
-            _type_: _description_
+            dict: Response of the HTTP request.
         """
 
         payload = {
@@ -225,7 +415,7 @@ class OTAC:
             request_url,
         )
         response = requests.post(
-            url=request_url, data=payload, headers=requestHeaders, timeout=None
+            url=request_url, data=payload, headers=REQUEST_FORM_HEADERS, timeout=None
         )
         if not response.ok:
             logger.error(
@@ -245,7 +435,7 @@ class OTAC:
         cert_path: str,
         permissions: str = "rcud",
     ):
-        """Put Certificate on Archive Center
+        """Put Certificate on Archive Center via SOAP Call
 
         Args:
             auth_id (str): ID of Certification
@@ -259,7 +449,7 @@ class OTAC:
 
         # Check if the photo file exists
         if not os.path.isfile(cert_path):
-            logger.error("Certificate file -> %s not found!", cert_path)
+            logger.error("Certificate file -> '%s' not found!", cert_path)
             return None
 
         with open(file=cert_path, mode="r", encoding="utf-8") as cert_file:
@@ -268,14 +458,16 @@ class OTAC:
         # Check that we have the pem certificate file - this is what OTAC expects.
         # If the file content is base64 encoded we will decode it
         if "BEGIN CERTIFICATE" in cert_content:
-            logger.info("Certificate file -> %s is not base64 encoded", cert_path)
+            logger.debug("Certificate file -> '%s' is not base64 encoded", cert_path)
         elif "BEGIN CERTIFICATE" in base64.b64decode(
             cert_content, validate=True
         ).decode("utf-8"):
-            logger.info("Certificate file -> %s is base64 encoded", cert_path)
+            logger.debug("Certificate file -> '%s' is base64 encoded", cert_path)
             cert_content = base64.b64decode(cert_content, validate=True).decode("utf-8")
         else:
-            logger.error("Certificate file -> %s is not in the right format", cert_path)
+            logger.error(
+                "Certificate file -> '%s' is not in the right format", cert_path
+            )
             return None
 
         request_url = (
@@ -287,14 +479,17 @@ class OTAC:
             + "&permissions="
             + permissions
         )
-        logger.info(
-            "Putting certificate -> %s on Archive -> %s; calling -> %s",
+        logger.debug(
+            "Putting certificate -> '%s' on Archive -> '%s'; calling -> %s",
             cert_path,
             logical_archive,
             request_url,
         )
         response = requests.put(
-            url=request_url, data=cert_content, headers=requestHeaders, timeout=None
+            url=request_url,
+            data=cert_content,
+            headers=REQUEST_FORM_HEADERS,
+            timeout=None,
         )
 
         if not response.ok:
@@ -302,7 +497,7 @@ class OTAC:
                 '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN'
             )[0]
             logger.error(
-                "Failed to put certificate -> %s on Archive -> %s; error -> %s",
+                "Failed to put certificate -> '%s' on Archive -> '%s'; error -> %s",
                 cert_path,
                 logical_archive,
                 message,
@@ -312,19 +507,21 @@ class OTAC:
 
     # end method definition
 
-    def enable_cert(self, auth_id: str, logical_archive: str, enable: bool = True):
-        """Enables Certitificate on Archive Center
+    def enable_cert(
+        self, auth_id: str, logical_archive: str, enable: bool = True
+    ) -> bool:
+        """Enables Certitificate on Archive Center via SOAP call
 
         Args:
             auth_id (str): Client ID
             logical_archive (str): Archive ID
             enable (bool, optional): Enable or Disable certificate. Defaults to True.
         Returns:
-            response or None if request fails.
+            True if certificate has been activated, False if an error has occured.
         """
 
         if not self._soap_token:
-            self._soap_login()
+            self.authenticate_soap()
 
         if enable:
             enabled: int = 1
@@ -347,15 +544,104 @@ class OTAC:
                     {"key": "CERT_FLAGS", "data": enabled},
                 ],
             )
-            return response
+            # With SOAP, no response is a good response!
+            if not response:
+                logger.debug("Archive Center certificate has been activated.")
+                return True
+            elif response.code == 500:
+                logger.error(
+                    "Failed to activate Archive Center certificate for Client -> %s on Archive -> '%s'!",
+                    auth_id,
+                    logical_archive,
+                )
+                return False
 
         except WebFault as exception:
             logger.error(
-                "Failed to execute SetCertificateFlags for Client -> %s on Archive -> %s; error -> %s",
+                "Failed to execute SetCertificateFlags for Client -> %s on Archive -> '%s'; error -> %s",
                 auth_id,
                 logical_archive,
                 exception,
             )
-            return None
+            return False
+
+    # end method definition
+
+    def enable_certificate(
+        self, cert_name: str, cert_type: str, logical_archive: str | None = None
+    ) -> dict | None:
+        """Enable a certificate via the new REST API (replacing the old SOAP interface)
+
+        Args:
+            cert_name (str): Name of the certificate
+            cert_type (str): Type of the certificate
+            logical_archive (str, optional): Logical archive name. If empty it is a global certificate
+                                             for all logical archives in Archive Center.
+
+        Returns:
+            dict | None: REST response or None if the request fails
+
+            Example response:
+            {
+                'IDNO': '3',
+                'CERT_NAME': 'SP_otcs-admin-0',
+                'IMPORT_TIMESTAMP': '1714092017',
+                'CERT_TYPE': 'ARC',
+                'ASSIGNED_ARCHIVE': None,
+                'FINGER_PRINT': 'B9F5 AF66 7CE6 C613 2B3C CAEE 96B6 4F79 97BB 5470 ',
+                'ENABLED': True,
+                'CERTIFICATE': '...',
+                'PRIVILEGES': {'read': True, 'create': True, 'update': True, 'delete': True}
+            }
+        """
+
+        request_url = (
+            self.config()["certUrl"]
+            + "?cert_name="
+            + cert_name
+            + "&cert_type="
+            + cert_type
+        )
+        if logical_archive:
+            request_url += "&assigned_archive=" + logical_archive
+
+        request_header = self.request_json_header()
+
+        payload = {"ENABLED": True}
+
+        logger.debug(
+            "Enabling certificate -> '%s' of type -> '%s' to Archive Center; calling -> %s",
+            cert_name,
+            cert_type,
+            request_url,
+        )
+
+        retries = 0
+        while True:
+            response = requests.put(
+                url=request_url,
+                headers=request_header,
+                data=json.dumps(payload),
+                timeout=REQUEST_TIMEOUT,
+            )
+            if response.ok:
+                logger.debug(
+                    "Certificate -> '%s' has been enabled on Archive Center keystore",
+                    cert_name,
+                )
+                return self.parse_request_response(response)
+            # Check if Session has expired - then re-authenticate and try once more
+            elif response.status_code == 401 and retries == 0:
+                logger.debug("Session has expired - try to re-authenticate...")
+                self.authenticate(revalidate=True)
+                retries += 1
+            else:
+                logger.error(
+                    "Failed to enable certificate -> '%s' in Archive Center; status -> %s; error -> %s",
+                    cert_name,
+                    response.status_code,
+                    response.text,
+                )
+                return None
 
     # end method definition