pdmv-http-client 2.1.0__py3-none-any.whl

rest/client/auth/auth_interface.py

@@ -0,0 +1,102 @@
+"""
+Main operations to load, save and renew credentials
+for an HTTP client session.
+"""
+
+from abc import ABC, abstractmethod
+
+from requests import Response, Session
+
+
+class AuthInterface(ABC):
+    """
+    Defines the main operations to set a credential
+    to authenticate and authorize HTTP requests targeting CERN
+    web applications.
+
+    For this context, a credential could be:
+        - OAuth2 token: Requested via `Client Credentials` or `Device Authorization` grants.
+            - Format: JSON Web Tokens (JWT)
+        - HTTP cookie: A cookie file requested using CERN internal packages.
+            - Format: Netscape Cookie
+
+    For more details, check the `handlers` module.
+    """
+
+    @abstractmethod
+    def _load_credential(self):
+        """
+        Loads a credential from the given path.
+
+        Returns:
+            None: In case it was not possible to load a credential
+                from the given path.
+        """
+        ...
+
+    @abstractmethod
+    def _request_credential(self):
+        """
+        Requests a credential to the CERN Auth service.
+
+        Raises:
+            PermissionError: If it is not possible to obtain a credential
+                because the CERN Auth service refused the request.
+            RuntimeError: Wrapper for any other possible error cause, the
+                original exception must be chained with this one.
+        """
+        ...
+
+    @abstractmethod
+    def _save_credential(self) -> None:
+        """
+        Saves a valid credential in a file into the provided path.
+
+        Raises:
+            OSError: In case it is not possible to store the file
+                in the provided path because lack of permissions to write
+                in the destination.
+        """
+        ...
+
+    @abstractmethod
+    def authenticate(self) -> None:
+        """
+        Provides an entry point to automatically scan if it is possible
+        to set credentials by picking them from default locations
+        or requests them to the CERN Auth service. Also, this is useful
+        for renewing credentials when they are expired.
+        """
+        ...
+
+    @abstractmethod
+    def configure(self, session: Session) -> Session:
+        """
+        Configures the given `request.Session` instance to set
+        the credential to perform authenticated requests.
+        """
+        ...
+
+    @classmethod
+    def validate_response(cls, response: Response) -> bool:
+        """
+        Checks that a given response has been redirected to
+        the CERN Authentication login server or been rejected by it
+        server because of a lack of permissions.
+
+        Args:
+            response: Response to check
+
+        Returns:
+            True: If the response was resolved by the requested web server
+                and its status code is not 401 nor 403.
+            False: If the response code was 401 or 403 or the resolver
+                was the CERN Authentication service.
+        """
+        # Intercepted and redirected to the authentication page.
+        if response.url.startswith(
+            "https://auth.cern.ch/auth/realms/cern"
+        ) or response.status_code in (401, 403):
+            return False
+
+        return True

rest/client/auth/handlers/oauth2_tokens.py

@@ -0,0 +1,307 @@
+"""
+This module provides a handler
+to authenticate requests using OAuth2 tokens.
+"""
+
+import json
+import os
+from json import JSONDecodeError
+from pathlib import Path
+
+import requests
+from requests.sessions import Session
+
+from rest.client.auth.auth_interface import AuthInterface
+from rest.utils.logger import LoggerFactory
+
+
+class AccessTokenHandler(AuthInterface):
+    """
+    Loads an access token from a JSON file and configures
+    an HTTP session to make use of it. This implements the API
+    access procedure described in:
+
+        - https://auth.docs.cern.ch/user-documentation/oidc/api-access/
+
+    Attributes:
+        _url: Target web application URL.
+        _credential: A JSON object including the access token, the refresh token
+            and some metadata.
+        _credential_path: Path to load the access token from or to persist in.
+        _client_id: ID for the client application, registered in the application portal,
+            to be use
+        -client_secret: Secret for the client application.
+        _target_application: Client ID linked to the target web
+            application.
+    """
+
+    TOKEN_ENDPOINT = "https://auth.cern.ch/auth/realms/cern/api-access/token"
+
+    def __init__(
+        self,
+        url: str,
+        credential_path: Path,
+        client_id: str,
+        client_secret: str,
+        target_application: str,
+    ) -> None:
+        self._url = url
+        self._credential_path = credential_path
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._target_application = target_application
+        self._credential: dict = {}
+        self._logger = LoggerFactory.getLogger("pdmv-http-client.client")
+
+    def _load_credential(self) -> dict:
+        try:
+            with open(file=self._credential_path, encoding="utf-8") as f:
+                credential = json.load(f)
+                return credential
+        except (OSError, JSONDecodeError):
+            return {}
+
+    def _request_credential(self) -> dict:
+        access_token = requests.post(
+            url=AccessTokenHandler.TOKEN_ENDPOINT,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+                "audience": self._target_application,
+            },
+        )
+
+        if access_token.status_code != 200:
+            msg = (
+                f"Error requesting access token ({access_token.status_code}): "
+                f"{json.dumps(access_token.json(), indent=4)}"
+            )
+            raise PermissionError(msg)
+
+        return access_token.json()
+
+    def _save_credential(self) -> None:
+        with open(file=self._credential_path, mode="w", encoding="utf-8") as f:
+            json.dump(obj=self._credential, fp=f, indent=4)
+
+        os.chmod(path=self._credential_path, mode=0o600)
+
+    def authenticate(self) -> None:
+        loaded_access_token = self._load_credential()
+        if self._validate(access_token=loaded_access_token):
+            self._credential = loaded_access_token
+            return
+
+        # Access token is not valid anymore, request another one
+        self._logger.debug("Access token is not valid, requesting a new one")
+        new_access_token = self._request_credential()
+        if self._validate(access_token=new_access_token):
+            self._credential = new_access_token
+            self._save_credential()
+            return
+
+    def configure(self, session: Session) -> Session:
+        if not self._credential:
+            self.authenticate()
+
+        raw_access_token = self._credential.get("access_token", "")
+        session.headers.update({"Authorization": f"Bearer {raw_access_token}"})
+        return session
+
+    def _validate(self, access_token: dict) -> bool:
+        """
+        Checks if the provided access token is valid to consume a resource in
+        the target web application.
+
+        Args:
+            access_token: OAuth2 access token retrieve from
+                CERN Authentication service.
+        """
+        raw_access_token = access_token.get("access_token", "")
+        test_response = requests.get(
+            self._url, headers={"Authorization": f"Bearer {raw_access_token}"}
+        )
+        return self.validate_response(test_response)
+
+
+class IDTokenHandler(AuthInterface):
+    """
+    Loads an ID token from a file or requests a new one
+    via Device Code Authorization Grant or refresh tokens (in case it is
+    provided in the JSON file). This implements the process described at:
+
+    - https://auth.docs.cern.ch/user-documentation/oidc/device-code/
+
+    Attributes:
+        _url: Target web application URL.
+        _credential: A JSON object including the access token, the refresh token
+            and some metadata.
+        _credential_path: Path to load the access token from or to persist in.
+        _client_id: ID for the client application, registered in the application portal,
+            to use. This application MUST be configured as a public client, so that no
+            client secret is required.
+        _target_application: Client ID linked to the target web
+            application.
+    """
+
+    TOKEN_ENDPOINT = (
+        "https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/token"
+    )
+    DEVICE_ENDPOINT = (
+        "https://auth.cern.ch/auth/realms/cern/protocol/openid-connect/auth/device"
+    )
+
+    def __init__(
+        self,
+        url: str,
+        credential_path: Path,
+        target_application: str,
+    ) -> None:
+        self._url = url
+        self._credential_path = credential_path
+        self._target_application = target_application
+        self._credential: dict = {}
+        self._logger = LoggerFactory.getLogger("pdmv-http-client.client")
+
+    def _load_credential(self) -> dict:
+        try:
+            with open(file=self._credential_path, encoding="utf-8") as f:
+                credential = json.load(f)
+                return credential
+        except (OSError, JSONDecodeError):
+            return {}
+
+    def _refresh_token(self) -> dict:
+        """
+        Renews the current ID token by requesting a new one
+        using the available refresh token.
+
+        Returns:
+            dict: ID token.
+        """
+        refresh_request = requests.post(
+            url=IDTokenHandler.TOKEN_ENDPOINT,
+            data={
+                "grant_type": "refresh_token",
+                "client_id": self._target_application,
+                "refresh_token": self._credential.get("refresh_token", ""),
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        details = refresh_request.json()
+        if refresh_request.status_code != 200:
+            self._logger.debug(
+                "Unable to refresh ID token (HTTP code: %s), details: %s",
+                refresh_request.status_code,
+                json.dumps(refresh_request.json(), indent=4),
+            )
+            return {}
+
+        id_token = details
+        return id_token
+
+    def _request_new_id_token(self) -> dict:
+        """
+        Request a new ID token to the authentication service
+        using a Device Code Authorization Grant. This requires
+        human interaction to complete the flow
+
+        Returns:
+            dict: ID token.
+        """
+        # Request a device code pre-authentication.
+        device_code = requests.post(
+            url=IDTokenHandler.DEVICE_ENDPOINT,
+            data={"client_id": self._target_application},
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        self._logger.info(
+            "Go to: %s\n", device_code.json()["verification_uri_complete"]
+        )
+        input("Press Enter once you have authenticated...")
+
+        code_details: dict = device_code.json()
+        if device_code.status_code == 401:
+            msg = (
+                f"Make sure the application ({self._target_application}) is configured as a public client"
+                f"Error: {json.dumps(code_details, indent=4)}"
+            )
+            raise PermissionError(msg)
+
+        # Request the ID token
+        device_completion = requests.post(
+            url=IDTokenHandler.TOKEN_ENDPOINT,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": code_details["device_code"],
+                "client_id": self._target_application,
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        completion_details = device_completion.json()
+        if device_completion.status_code != 200:
+            msg = (
+                f"Unable to request an ID token\n"
+                f"Error: {json.dumps(completion_details, indent=4)}"
+            )
+            raise PermissionError(msg)
+
+        id_token = completion_details
+        return id_token
+
+    def _request_credential(self) -> dict:
+        # Attempt to refresh the token
+        id_token = self._refresh_token()
+        if id_token:
+            return id_token
+
+        # Request a new ID token
+        self._logger.debug(
+            "Requesting new ID token, asking the user to manually complete the flow"
+        )
+        return self._request_new_id_token()
+
+    def _save_credential(self) -> None:
+        with open(file=self._credential_path, mode="w", encoding="utf-8") as f:
+            json.dump(obj=self._credential, fp=f, indent=4)
+
+        os.chmod(path=self._credential_path, mode=0o600)
+
+    def authenticate(self) -> None:
+        loaded_id_token = self._load_credential()
+        if self._validate(id_token=loaded_id_token):
+            self._credential = loaded_id_token
+            return
+
+        # ID token is not valid anymore, request another one
+        self._logger.debug("ID token is not valid, requesting a new one")
+        new_id_token = self._request_credential()
+        if self._validate(id_token=new_id_token):
+            self._credential = new_id_token
+            self._save_credential()
+            return
+
+    def configure(self, session: Session) -> Session:
+        if not self._credential:
+            self.authenticate()
+
+        raw_access_token = self._credential.get("access_token", "")
+        session.headers.update({"Authorization": f"Bearer {raw_access_token}"})
+        return session
+
+    def _validate(self, id_token: dict) -> bool:
+        """
+        Checks if the provided ID token is valid to consume a resource in
+        the target web application.
+
+        Args:
+            id_token: OIDC ID token retrieve from
+                CERN Authentication service.
+        """
+        raw_access_token = id_token.get("access_token", "")
+        test_response = requests.get(
+            self._url, headers={"Authorization": f"Bearer {raw_access_token}"}
+        )
+        return self.validate_response(test_response)

rest/client/auth/handlers/session_cookies.py

@@ -0,0 +1,110 @@
+"""
+This module provides a handler
+to load a cookie from the file system.
+"""
+
+import os
+from http.cookiejar import LoadError, MozillaCookieJar
+from pathlib import Path
+from typing import Union
+
+import requests
+from requests.sessions import Session
+
+from rest.client.auth.auth_interface import AuthInterface
+from rest.utils.logger import LoggerFactory
+from rest.utils.shell import run_command
+
+
+class SessionCookieHandler(AuthInterface):
+    """
+    Loads a Netscape cookie from a file and configures
+    an HTTP session to make use of it.
+
+    Attributes:
+        _url: Target web application URL.
+        _credential: Session cookie loaded from a Netscape file.
+    """
+
+    def __init__(self, url: str, credential_path: Path):
+        self._url = url
+        self._credential_path = credential_path
+        self._credential: Union[MozillaCookieJar, None] = None
+        self._logger = LoggerFactory.getLogger("pdmv-http-client.client")
+
+    def _load_credential(self) -> Union[MozillaCookieJar, None]:
+        try:
+            cookie = MozillaCookieJar(self._credential_path)
+            cookie.load()
+            return cookie
+        except (LoadError, OSError):
+            return None
+
+    def _request_credential(self) -> MozillaCookieJar:
+        # Remove the cookie file in case there's available
+        self._credential_path.unlink(missing_ok=True)
+
+        # Request a session cookie using CERN internal packages.
+        command = (
+            f"auth-get-sso-cookie -u '{self._url}' -o '{str(self._credential_path)}'"
+        )
+        _, stderr, exit_code = run_command(command=command)
+
+        # Most likely the package is not available or
+        # there's no valid Kerberos ticket.
+        if exit_code != 0 or stderr:
+            msg = (
+                f"Session cookie requested via: '{command}'\n"
+                f"Standard error: {stderr}\n"
+            )
+            raise RuntimeError(msg)
+
+        # Load the cookie
+        return self._load_credential()
+
+    def _save_credential(self) -> None:
+        # Credential is already stored, just change its permissions.
+        os.chmod(path=self._credential_path, mode=0o600)
+
+    def authenticate(self) -> None:
+        loaded_cookie = self._load_credential()
+        if self._validate(cookie=loaded_cookie):
+            self._credential = loaded_cookie
+            self._save_credential()
+            return
+
+        # The credential is not valid anymore, renew it.
+        self._logger.debug("Session cookie is not valid, requesting a new one")
+        renewed_cookie = self._request_credential()
+        if self._validate(cookie=renewed_cookie):
+            self._credential = renewed_cookie
+            self._save_credential()
+            return
+
+        # It is not possible to authenticate a request
+        # using session cookies.
+        msg = (
+            f"Unable to consume a resource in the target web application ({self._url}) "
+            "using session cookies.\n"
+            "Remember this method only works if 2FA is not enabled.\n"
+            "Please use another authentication strategy instead."
+        )
+        raise PermissionError(msg)
+
+    def configure(self, session: Session) -> Session:
+        if not self._credential:
+            self.authenticate()
+
+        session.cookies.update(self._credential)
+        return session
+
+    def _validate(self, cookie: MozillaCookieJar) -> bool:
+        """
+        Checks if the provided cookie is valid to consume a resource in
+        the target web application.
+
+        Args:
+            cookie: Cookie to check.
+        """
+        test_response = requests.get(self._url, cookies=cookie)
+        return self.validate_response(test_response)

rest/client/session.py

@@ -0,0 +1,99 @@
+"""
+Configures a request HTTP session so that it handles authentication
+to the web service automatically.
+"""
+
+from pathlib import Path
+from typing import Union
+
+import requests
+
+from rest.client.auth.auth_interface import AuthInterface
+from rest.client.auth.handlers.oauth2_tokens import AccessTokenHandler, IDTokenHandler
+from rest.client.auth.handlers.session_cookies import SessionCookieHandler
+from rest.utils.logger import LoggerFactory
+
+
+class AuthenticatedSession(requests.Session):
+    def __init__(self, handler: AuthInterface) -> None:
+        super().__init__()
+        self._handler = handler
+        self._max_attempts = 3
+        self._logger = LoggerFactory.getLogger("pdmv-http-client.client")
+        self._handler.configure(session=self)
+
+    def request(
+        self, method: Union[str, bytes], url: Union[str, bytes], *args, **kwargs
+    ) -> requests.Response:
+        for attempt, _ in enumerate(range(self._max_attempts), start=1):
+            # Restart the session and send the request
+            with self:
+                response = super().request(method, url, *args, **kwargs)
+
+            if self._handler.validate_response(response):
+                return response
+            else:
+                # Re-authenticate and return the response.
+                self._logger.debug(
+                    "(%s/%s) Credentials expired, renewing them and retrying the request",
+                    attempt,
+                    self._max_attempts,
+                )
+                self._handler.authenticate()
+                self._handler.configure(session=self)
+
+        self._logger.warning(
+            "Unable to renew credentials for (%s) after %s attempts: HTTP code %s",
+            response.url,
+            self._max_attempts,
+            response.status_code,
+        )
+        return response
+
+
+class SessionFactory:
+    """
+    Provides a pre-configured `request.Session` with the
+    required authentication method.
+    """
+
+    @classmethod
+    def configure_by_session_cookie(
+        cls, url: str, credential_path: Path
+    ) -> requests.Session:
+        session_cookie_handler = SessionCookieHandler(
+            url=url, credential_path=credential_path
+        )
+        return AuthenticatedSession(handler=session_cookie_handler)
+
+    @classmethod
+    def configure_by_access_token(
+        cls,
+        url: str,
+        credential_path: Path,
+        client_id: str,
+        client_secret: str,
+        target_application: str,
+    ) -> requests.Session:
+        access_token_handler = AccessTokenHandler(
+            url=url,
+            credential_path=credential_path,
+            client_id=client_id,
+            client_secret=client_secret,
+            target_application=target_application,
+        )
+        return AuthenticatedSession(handler=access_token_handler)
+
+    @classmethod
+    def configure_by_id_token(
+        cls,
+        url: str,
+        credential_path: Path,
+        target_application: str,
+    ) -> requests.Session:
+        id_token_handler = IDTokenHandler(
+            url=url,
+            credential_path=credential_path,
+            target_application=target_application,
+        )
+        return AuthenticatedSession(handler=id_token_handler)

rest/utils/logger.py

@@ -0,0 +1,36 @@
+"""
+This module configures the library logger,
+its message format and its level.
+"""
+
+import logging
+import sys
+
+
+class LoggerFactory:
+    _instances: dict[str, logging.Logger] = {}
+
+    @classmethod
+    def _create_logger(cls, name: str) -> logging.Logger:
+        logger = logging.getLogger(name=name)
+        if not logger.hasHandlers():
+            format = "[%(asctime)s][%(levelname)s][%(name)s]: %(message)s"
+            date_format = "%Y-%m-%d %H:%M:%S %z"
+            handler = logging.StreamHandler(stream=sys.stdout)
+            formatter = logging.Formatter(fmt=format, datefmt=date_format)
+
+            handler.setFormatter(formatter)
+            logger.addHandler(handler)
+            logger.setLevel(logging.INFO)
+
+        return logger
+
+    @classmethod
+    def getLogger(cls, name: str) -> logging.Logger:
+        logger = cls._instances.get(name)
+        if logger:
+            return logger
+
+        logger = cls._create_logger(name)
+        cls._instances[name] = logger
+        return logger