earthscope-sdk 0.2.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

earthscope_sdk/auth/client_credentials_flow.py

@@ -1,190 +1,70 @@
-from dataclasses import dataclass
-from pathlib import Path
-import json
 import logging
-import requests
+from json import JSONDecodeError
 
-from earthscope_sdk.auth.auth_flow import (
-    AuthFlow,
-    AuthFlowError,
-    NoTokensError,
-    UnauthorizedError,
-    ValidTokens
-)
+from earthscope_sdk.auth.auth_flow import AuthFlow
+from earthscope_sdk.auth.error import ClientCredentialsFlowError, UnauthorizedError
+from earthscope_sdk.common.context import SdkContext
 
 logger = logging.getLogger(__name__)
 
 
-class ClientCredentialsFlowError(AuthFlowError):
-    pass
-
-
-@dataclass
-class ClientCredentials:
-    client_id: str
-    client_secret: str
-
-
-@dataclass
-class GetTokensErrorResponse:
-    error: str
-    error_description: str
-
-
 class ClientCredentialsFlow(AuthFlow):
     """
-    This is an abstract subclass of the AuthFlow abstract class. This class handles the client credential flow actions.
-
-    Attributes
-    __________
-    audience : str
-        Auth0 API Identifier (default is 'https://account.earthscope.org')
-    domain : str
-        Auth0 tenant domain URL or custom domain (default is 'login.earthscope.org')
-    client_credentials: ClientCredentials
-        The client credentials - client id and client secret
-    _secret: str
-        The client secret of the machine-to-machine application from the client_credentials
-
-    Methods
-    -------
-    request_tokens
-        Request the token from Auth0. Validates and saves the token locally.
+    Implements the oauth2 Client Credentials "machine-to-machine" (M2M) flow.
     """
-    def __init__(
-        self, domain: str, audience: str, client_credentials: ClientCredentials
-    ) -> None:
-        if not client_credentials or not client_credentials.client_secret:
-            raise ValueError("Client secret missing")
 
-        super().__init__(
-            domain=domain,
-            audience=audience,
-            client_id=client_credentials.client_id,
-            scope="",
-        )
-        # Flow management vars
-        self._secret = client_credentials.client_secret
+    def __init__(self, ctx: SdkContext):
+        if not ctx.settings.oauth2.client_secret:
+            raise ValueError("Client secret required for client credentials flow")
 
-    def get_token_or_request_if_expired(self):
-        """
-        Loads the access token if it is currently saved locally.
-        Requests the token if the token is expired or if no token is found locally
-        """
-        try:
-            self.load_tokens()
-            if self.ttl.total_seconds() <= 0:
-                self.request_tokens()
+        super().__init__(ctx=ctx)
 
-        except NoTokensError:
-                self.request_tokens()
+        # httpx.Auth objects can be used in either sync or async clients so we
+        # facilitate both from the same class
+        self.request_tokens = ctx.syncify(self.async_request_tokens)
 
-        return self.access_token
+    async def async_refresh(self, *args, **kwargs):
+        # alias for self.request_tokens() so that base class can get new tokens automagically
+        return await self.async_request_tokens()
 
-    def request_tokens(self):
+    async def async_request_tokens(self):
         """
-        Request the token from Auth0. Validates and saves the token locally.
+        Request access token from IdP
 
-        Raises
-        ------
-        Unauthorized Error
-            If the request returns as unauthorized
-        ClientCredentialsFlowError
-            If there is an error in the clientcredentials flow other than unauthorized
+        Raises:
+            Unauthorized Error: the request returns as unauthorized
+            ClientCredentialsFlowError: unhandled error in the client credentials flow
         """
-        r = requests.post(
-            f"https://{self.auth0_domain}/oauth/token",
+        r = await self._ctx.httpx_client.post(
+            f"{self._settings.domain}oauth/token",
+            auth=None,  # override client default
             headers={"content-type": "application/x-www-form-urlencoded"},
             data={
                 "grant_type": "client_credentials",
-                "client_id": self.auth0_client_id,
-                "client_secret": self._secret,
-                "audience": self.auth0_audience,
+                "client_id": self._settings.client_id,
+                "client_secret": self._settings.client_secret.get_secret_value(),
+                "audience": self._settings.audience,
             },
         )
+        try:
+            resp: dict = r.json()
+        except JSONDecodeError:
+            raise ClientCredentialsFlowError(
+                f"Unable to unpack IdP response: {r.content}"
+            )
+
+        # Success!
         if r.status_code == 200:
-            self.validate_and_save_tokens(r.json())
+            self._validate_and_save_tokens(resp)
+
             logger.debug(f"Got tokens: {self.tokens}")
             return self
 
+        # Unauthorized
         if r.status_code == 401:
-            err = GetTokensErrorResponse(**r.json())
-            if err.error == "access_denied":
-                if err.error_description == "Unauthorized":
-                    raise UnauthorizedError
-
-        raise ClientCredentialsFlowError
+            raise UnauthorizedError(
+                f"m2m client '{self._settings.client_id}' is not authorized. IdP response: {resp}"
+            )
 
-
-class ClientCredentialsFlowSimple(ClientCredentialsFlow):
-    """
-    A simple concrete implementation of the ClientCredentialsFlow class. This will store and load tokens on your filesystem
-
-    Attributes:
-    -----------
-    audience : str, optional
-        Auth0 API Identifier (default is 'https://account.earthscope.org')
-    client_credentials: ClientCredentials
-        the client credentials
-    domain : str, optional
-        Auth0 tenant domain URL or custom domain (default is 'login.earthscope.org')
-    path : str
-        The path where your access token will be stored and read
-
-    Methods
-    -------
-    load_tokens
-        Loads and validates your access token from the location specified by the given path.
-    save_tokens(creds)
-        Saves your access token to the location specified by the given path.
-    """
-    def __init__(
-        self,
-        client_id: str,
-        client_secret: str,
-        path: str,
-        domain: str = "login.earthscope.org",
-        audience: str = "https://account.earthscope.org",
-    ) -> None:
-        super().__init__(
-            domain=domain,
-            audience=audience,
-            client_credentials=ClientCredentials(
-                client_id=client_id, client_secret=client_secret
-            ),
-        )
-        self.path = Path(path)
-
-    def load_tokens(self):
-        """
-        Loads and validates the access token from the location specified by the given path.
-
-        Raises
-        ------
-        NoTokensError
-            If no token is found
-        Returns
-        _______
-        valid token : str
-        """
-        try:
-            with self.path.open() as f:
-                json_state = json.load(f)
-        except FileNotFoundError:
-            raise NoTokensError
-
-        self.validate_tokens(json_state)
-        return self.tokens
-
-    def save_tokens(self, creds: ValidTokens):
-        """
-        Writes the token to the location specified by the given path in json format.
-
-        Parameters
-        ----------
-        creds: ValidTokens
-            token credentials
-        """
-        json_str_state = json.dumps(vars(creds))
-        with self.path.open("w") as f:
-            f.write(json_str_state)
+        # Unhandled
+        raise ClientCredentialsFlowError("client credentials flow failed", r.content)

earthscope_sdk/auth/device_code_flow.py

@@ -1,16 +1,20 @@
-import json
 import logging
-import requests
-
-from abc import abstractmethod
-from dataclasses import dataclass
+from asyncio import sleep
+from contextlib import asynccontextmanager, contextmanager
 from enum import Enum
-from pathlib import Path
-from time import sleep
+from json import JSONDecodeError
 from typing import Optional
 
-from earthscope_sdk.auth.auth_flow import AuthFlow, NoTokensError, ValidTokens
+from pydantic import BaseModel, ValidationError
 
+from earthscope_sdk.auth.auth_flow import AuthFlow
+from earthscope_sdk.auth.error import (
+    DeviceCodePollingError,
+    DeviceCodePollingExpiredError,
+    DeviceCodeRequestDeviceCodeError,
+    UnauthorizedError,
+)
+from earthscope_sdk.common.context import SdkContext
 
 logger = logging.getLogger(__name__)
 
@@ -22,273 +26,225 @@ class PollingErrorType(str, Enum):
     ACCESS_DENIED = "access_denied"
 
 
-class RequestDeviceTokensError(RuntimeError):
-    pass
-
-
-class PollingError(ValueError):
-    pass
-
-
-class PollingExpiredError(PollingError):
-    pass
-
-
-class PollingAccessDeniedError(PollingError):
-    pass
-
-
-@dataclass
-class GetDeviceCodeResponse:
+class GetDeviceCodeResponse(BaseModel):
     device_code: str
     user_code: str
     verification_uri: str
     verification_uri_complete: str
     expires_in: int
-    interval: int
+    interval: float
 
 
-@dataclass
-class PollingErrorResponse:
+class PollingErrorResponse(BaseModel):
     error: PollingErrorType
     error_description: str
 
 
 class DeviceCodeFlow(AuthFlow):
     """
-    This is an abstract subclass of the AuthFlow abstract class. This class handles the device code flow actions.
-
-    Atttributes
-    -----------
-    domain : str
-        Auth0 tenant domain URL or custom domain
-    audience : str
-        Auth0 API Identifier
-    client_id : str
-        Identification value of Auth0 Application
-    scope : str
-        The specific actions Auth0 applications can be allowed to do or information that they can request on a user’s behalf
-    _is_polling: bool, optional
-        True if currently polling (default is False)
-    _device_codes, optional
-        The device code (default is None)
-
-    Methods
-    -------
-    do_flow
-        Requests the device code, prompts the user to complete the device code flow, polls while waiting for completion
-         and returns the token
-    poll
-        Polls for completion of the device code flow
-    prompt_user
-        abstract method for prompting the user to complette the device code  flow
-    request_device_code
-        requests the device code from Auth0
+    Implements the oauth2 Device Code flow.
     """
+
     @property
     def polling(self):
-        "If is in proccess of polling"
+        """
+        This instance is in the process of polling for tokens
+        """
         return self._is_polling
 
-    @property
-    def started(self):
-        "Returns a boolean on if the device code flow has started"
-        return self._device_codes is not None
-
-    def __init__(self, domain: str, audience: str, client_id: str, scope: str) -> None:
-        super().__init__(
-            domain=domain,
-            audience=audience,
-            client_id=client_id,
-            scope=scope,
-        )
+    def __init__(self, ctx: SdkContext):
+        if ctx.settings.oauth2.client_secret:
+            raise ValueError("Client secret should not be used with device code flow")
+
+        super().__init__(ctx=ctx)
+
         # Flow management vars
         self._is_polling = False
-        self._device_codes: Optional[GetDeviceCodeResponse] = None
 
-    def do_flow(self):
-        """
-        Runs request_device_code, prompt_user, and poll methods. This is the device code flow "login" process.
+        # httpx.Auth objects can be used in either sync or async clients so we
+        # facilitate both from the same class
+        self._poll = ctx.syncify(self._async_poll)
+        self._request_device_code = ctx.syncify(self._async_request_device_code)
 
-        Returns
-        -------
-        token
+    @asynccontextmanager
+    async def async_do_flow(self, scope: Optional[str] = None):
+        """
+        Perform the oauth2 Device Code flow:
+        - requests device code
+        - yields the device code to the caller for them to prompt the user
+        - polls for access token
+
+        Args:
+            scope: the specific oauth2 scopes to request
+
+        Yields:
+            GetDeviceCodeResponse: the device code response that must be shown to the user
+                to facilitate a login.
+
+        Raises:
+            DeviceCodeRequestDeviceCodeError: failed to get a device code from the IdP
+            DeviceCodePollingExpiredError: the polling token expired
+            UnauthorizedError: access denied
+            DeviceCodePollingError: unhandled polling error
+
+        Examples:
+            >>> async with device_flow.async_do_flow() as codes:
+            ...     # prompt the user to login using the device code
+            ...     print(f"Open the following URL in a web browser to login: {codes.verification_uri_complete}")
         """
-        self.request_device_code()
-        self.prompt_user()
-        self.poll()
-        return self.tokens
+        # NOTE: if you update this method, also update the synchronous version
+
+        codes = await self._async_request_device_code(scope=scope)
+
+        # Yield codes to facilitate prompting the user
+        yield codes
+
+        await self._async_poll(codes=codes)
 
-    def poll(self):
+    @contextmanager
+    def do_flow(self, scope: Optional[str] = None):
         """
-        Polling auth0 for token. Sets self._is_polling.
+        Perform the oauth2 Device Code flow:
+        - requests device code
+        - yields the device code to the caller for them to prompt the user
+        - polls for access token
+
+        Args:
+            scope: the specific oauth2 scopes to request
+
+        Yields:
+            GetDeviceCodeResponse: the device code response that must be shown to the user
+                to facilitate a login.
+
+        Raises:
+            DeviceCodeRequestDeviceCodeError: failed to get a device code from the IdP
+            DeviceCodePollingExpiredError: the polling token expired
+            UnauthorizedError: access denied
+            DeviceCodePollingError: unhandled polling error
+
+        Examples:
+            >>> with device_flow.do_flow() as codes:
+            ...     # prompt the user to login using the device code
+            ...     print(f"Open the following URL in a web browser to login: {codes.verification_uri_complete}")
         """
-        if not self._device_codes:
-            raise PollingError("Cannot poll without initial device code response")
+        # NOTE: we explicitly redefine this sync method because ctx.syncify()
+        # does not support generators
+
+        codes = self._request_device_code(scope=scope)
+
+        # Yield codes to facilitate prompting the user
+        yield codes
+
+        self._poll(codes=codes)
+
+    async def _async_poll(self, codes: GetDeviceCodeResponse):
+        """
+        Polling IdP for tokens.
+
+        Args:
+            codes: device code response from IdP after starting the flow
 
+        Raises:
+            DeviceCodePollingExpiredError: the polling token expired
+            UnauthorizedError: access denied
+            DeviceCodePollingError: unhandled polling error
+        """
         if self._is_polling:
-            raise PollingError("Attempted to double poll")
+            raise DeviceCodePollingError("Polling is already in progress")
 
         self._is_polling = True
         try:
             while True:
-                sleep(self._device_codes.interval)
+                # IdP-provided poll interval
+                await sleep(codes.interval)
 
-                r = requests.post(
-                    f"https://{self.auth0_domain}/oauth/token",
+                r = await self._ctx.httpx_client.post(
+                    f"{self._settings.domain}oauth/token",
+                    auth=None,  # override client default
                     headers={"content-type": "application/x-www-form-urlencoded"},
                     data={
                         "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
-                        "device_code": self._device_codes.device_code,
-                        "client_id": self.auth0_client_id,
+                        "device_code": codes.device_code,
+                        "client_id": self._settings.client_id,
                     },
                 )
+
+                try:
+                    resp: dict = r.json()
+                except JSONDecodeError:
+                    raise DeviceCodePollingError(
+                        f"Unable to unpack IdP response: {r.content}"
+                    )
+
+                # Success!
                 if r.status_code == 200:
-                    tokens = self.validate_and_save_tokens(r.json())
-                    logger.debug(f"Got tokens: {tokens}")
+                    self._validate_and_save_tokens(resp)
+
+                    logger.debug(f"Got tokens: {self.tokens}")
                     return self
 
-                poll_err = PollingErrorResponse(**r.json())
+                # Keep polling
+                try:
+                    poll_err = PollingErrorResponse.model_validate(resp)
+                except ValidationError as e:
+                    raise DeviceCodePollingError(
+                        f"Failed to unpack polling response: {r.text}"
+                    ) from e
                 if poll_err.error in [
                     PollingErrorType.AUTHORIZATION_PENDING,
                     PollingErrorType.SLOW_DOWN,
                 ]:
                     continue
 
+                # Timeout
                 if poll_err.error == PollingErrorType.EXPIRED_TOKEN:
-                    raise PollingExpiredError
+                    raise DeviceCodePollingExpiredError
 
+                # Unauthorized
                 if poll_err.error == PollingErrorType.ACCESS_DENIED:
-                    raise PollingAccessDeniedError
+                    raise UnauthorizedError
 
+                # Unhandled
                 if poll_err:
-                    raise PollingError(f"Unknown polling error: {poll_err}")
+                    raise DeviceCodePollingError(f"Unknown polling error: {poll_err}")
+
         finally:
             self._is_polling = False
 
-    @abstractmethod
-    def prompt_user(self):
-        pass
-
-    def request_device_code(self):
+    async def _async_request_device_code(self, scope: Optional[str] = None):
         """
-        Request the device code from auth0 and sets self._device_codes
+        Request new device code from IdP
+
+        Args:
+            scope: the specific oauth2 scopes to request
 
-        Raises
-        ------
-        RequestDeviceTokensError
-            failed to get a device code
+        Raises:
+            DeviceCodeRequestDeviceCodeError: failed to get a device code from the IdP
         """
-        r = requests.post(
-            f"https://{self.auth0_domain}/oauth/device/code",
+        scope = scope or self._settings.scope
+
+        r = await self._ctx.httpx_client.post(
+            f"{self._settings.domain}oauth/device/code",
+            auth=None,  # override client default
             headers={"content-type": "application/x-www-form-urlencoded"},
             data={
-                "client_id": self.auth0_client_id,
-                "scope": self.token_scope,
-                "audience": self.auth0_audience,
+                "client_id": self._settings.client_id,
+                "scope": scope,
+                "audience": self._settings.audience,
             },
         )
-        if r.status_code == 200:
-            self._device_codes = GetDeviceCodeResponse(**r.json())
-            logger.debug(f"Got device code response: {self._device_codes}")
-            return self
-
-        raise RequestDeviceTokensError(f"Failed to get a device code: {r.text}")
-
-
-class DeviceCodeFlowSimple(DeviceCodeFlow):
-    """
-    This is a concrete implementation of the DeviceCodeFlow abstract class. This will store tokens on your filesystem
-    and print the user prompt to the standard out.
-
-    Default Auth0 values are for the Production tenant for UNAVCO Data File Server Access Application and User Management API.
-
-    Attributes:
-    -----------
-    path : str
-        The path where your access token will be stored and read. If this is a directory, the file name will be assigned as sso_tokens.json. You maye provide your own file name if desired.
-    domain : str, optional
-        Auth0 tenant domain URL or custom domain (default is 'login.earthscope.org')
-    audience : str, optional
-        Auth0 API Identifier (default is 'https://account.earthscope.org')
-    client_id : str, optional
-        Identification value of Auth0 Application (default is 'b9DtAFBd6QvMg761vI3YhYquNZbJX5G0')
-    scope : str, optional
-        The specific actions Auth0 applications can be allowed to do or information that they can request on a user’s behalf. (default is "openid profile email offline_access")
-
-    Methods
-    -------
-    load_tokens
-        Loads and validates your access token from the location specified by the given path.
-    save_tokens(creds)
-        Saves your access token to the location specified by the given path.
-    prompt_user
-        Prints the link for the sso authorization flow.
-    """
-    def __init__(
-        self,
-            path: str,
-            domain: str = "login.earthscope.org",
-            audience: str = "https://account.earthscope.org",
-            client_id: str = "b9DtAFBd6QvMg761vI3YhYquNZbJX5G0",
-            scope: str = "openid profile email offline_access"
-
-    ) -> None:
-        super().__init__(
-            domain=domain,
-            audience=audience,
-            client_id=client_id,
-            scope=scope,
-        )
-        self.path = Path(path)
-        if self.path.is_dir():
-            self.path = self.path / "sso_tokens.json"
 
-    def load_tokens(self):
-        """
-        Loads and validates your access token from the location specified by the given path.
-
-        Raises
-        ------
-        NoTokensError
-            If no token is found
-        Returns
-        _______
-        valid token : str
-        """
-        try:
-            with self.path.open() as f:
-                json_state = json.load(f)
-        except FileNotFoundError:
-            raise NoTokensError
-
-        self.validate_tokens(json_state)
-        return self.tokens
-
-    def save_tokens(self, creds: ValidTokens):
-        """
-        writes your access token to the location specified by the given path in json format.
-
-        Parameters
-        ----------
-        creds: ValidTokens
-            token credentials
-        """
-        json_str_state = json.dumps(vars(creds))
-        with self.path.open("w") as f:
-            f.write(json_str_state)
-
-    def prompt_user(self):
-        """
-        Prints the url to complete the sso authorization flow to to stdout
-        """
-        if not self._device_codes:
-            raise RuntimeError(
-                "You must start the device flow before prompting the user"
+        if r.status_code != 200:
+            raise DeviceCodeRequestDeviceCodeError(
+                f"Failed to get a device code: {r.content}"
             )
 
-        print(
-            f"""To complete the SSO authorization, please visit the following URL in a browser of your choice:
-            {self._device_codes.verification_uri_complete}
-            """
-        )
+        try:
+            codes = GetDeviceCodeResponse.model_validate_json(r.content)
+        except ValidationError as e:
+            raise DeviceCodeRequestDeviceCodeError(
+                f"Failed to unpack device code response: {r.text}"
+            ) from e
+
+        logger.debug(f"Got device code response: {codes}")
+        return codes