feat: Adding examples for orgs api uptake and public oauth

README.md

@@ -86,6 +86,13 @@ After a brief delay, you will receive the text message on your phone.
 > **Warning**
 > It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
 
+## OAuth Feature for Twilio APIs
+We are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.
+
+API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/public_oauth.py)
+
+Organisation API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/organization_api_calls.py)
+
 ## Use the helper library
 
 ### API Credentials

examples/organization_api_calls.py

@@ -0,0 +1,28 @@
+import os
+
+from twilio.rest import Client
+from twilio.credential.orgs_credential_provider import OrgsCredentialProvider
+
+API_KEY = os.environ.get("TWILIO_API_KEY")
+API_SECRET = os.environ.get("TWILIO_API_SECRET")
+ACCOUNT_SID = os.environ.get("TWILIO_ACCOUNT_SID")
+CLIENT_ID = os.environ.get("TWILIO_CLIENT_ID")
+CLIENT_SECRET = os.environ.get("TWILIO_CLIENT_SECRET")
+ORGS_SID = os.environ.get("TWILIO_ORGS_SID")
+
+
+def example(self=None):
+    """
+    Some example usage of fetching accounts within an organization
+    """
+    self.client = Client(
+        username=API_KEY,
+        password=API_SECRET,
+        account_sid=ACCOUNT_SID,
+        credential_provider= OrgsCredentialProvider(CLIENT_ID, CLIENT_SECRET)
+    )
+    accounts = self.client.preview_iam.organization(organization_sid=ORGS_SID).accounts.stream()
+    self.assertIsNotNone(accounts)
+
+if __name__ == "__main__":
+    example()

examples/public_oauth.py

@@ -0,0 +1,35 @@
+import os
+
+from twilio.rest import Client
+from twilio.credential.client_credential_provider import ClientCredentialProvider
+
+API_KEY = os.environ.get("TWILIO_API_KEY")
+API_SECRET = os.environ.get("TWILIO_API_SECRET")
+ACCOUNT_SID = os.environ.get("TWILIO_ACCOUNT_SID")
+CLIENT_ID = os.environ.get("TWILIO_CLIENT_ID")
+CLIENT_SECRET = os.environ.get("TWILIO_CLIENT_SECRET")
+ORGS_SID = os.environ.get("TWILIO_ORGS_SID")
+FROM_NUMBER = os.environ.get("TWILIO_FROM_NUMBER")
+TO_NUMBER = os.environ.get("TWILIO_TO_NUMBER")
+
+
+def example(self=None):
+    """
+    Some example usage of fetching accounts within an organization
+    """
+    self.client = Client(
+        username=API_KEY,
+        password=API_SECRET,
+        account_sid=ACCOUNT_SID,
+        credential_provider= ClientCredentialProvider(CLIENT_ID, CLIENT_SECRET)
+    )
+    msg = self.client.messages.create(
+        to=self.to_number, from_=self.from_number, body="hello world"
+    )
+    self.assertEqual(msg.to, self.to_number)
+    self.assertEqual(msg.from_, self.from_number)
+    self.assertEqual(msg.body, "hello world")
+    self.assertIsNotNone(msg.sid)
+
+if __name__ == "__main__":
+    example()

twilio/auth_strategy/auth_strategy.py

@@ -0,0 +1,19 @@
+from twilio.auth_strategy.auth_type import AuthType
+from abc import abstractmethod
+
+
+class AuthStrategy(object):
+    def __init__(self, auth_type: AuthType):
+        self._auth_type = auth_type
+
+    @property
+    def auth_type(self) -> AuthType:
+        return self._auth_type
+
+    @abstractmethod
+    def get_auth_string(self) -> str:
+        """Return the authentication string."""
+
+    @abstractmethod
+    def requires_authentication(self) -> bool:
+        """Return True if authentication is required, else False."""

twilio/auth_strategy/auth_type.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class AuthType(Enum):
+    ORGS_TOKEN = "orgs_stoken"
+    NO_AUTH = "noauth"
+    BASIC = "basic"
+    API_KEY = "api_key"
+    CLIENT_CREDENTIALS = "client_credentials"
+
+    def __str__(self):
+        return self.value

twilio/auth_strategy/no_auth_strategy.py

@@ -0,0 +1,13 @@
+from auth_type import AuthType
+from twilio.auth_strategy.auth_strategy import AuthStrategy
+
+
+class NoAuthStrategy(AuthStrategy):
+    def __init__(self):
+        super().__init__(AuthType.NO_AUTH)
+
+    def get_auth_string(self) -> str:
+        return ""
+
+    def requires_authentication(self) -> bool:
+        return False

twilio/auth_strategy/token_auth_strategy.py

@@ -0,0 +1,53 @@
+import jwt
+import threading
+import logging
+from datetime import datetime
+
+from twilio.auth_strategy.auth_type import AuthType
+from twilio.auth_strategy.auth_strategy import AuthStrategy
+from twilio.http.token_manager import TokenManager
+
+
+class TokenAuthStrategy(AuthStrategy):
+    def __init__(self, token_manager: TokenManager):
+        super().__init__(AuthType.ORGS_TOKEN)
+        self.token_manager = token_manager
+        self.token = None
+        self.lock = threading.Lock()
+        logging.basicConfig(level=logging.INFO)
+        self.logger = logging.getLogger(__name__)
+
+    def get_auth_string(self) -> str:
+        self.fetch_token()
+        return f"Bearer {self.token}"
+
+    def requires_authentication(self) -> bool:
+        return True
+
+    def fetch_token(self):
+        if self.token is None or self.token == "" or self.is_token_expired(self.token):
+            with self.lock:
+                if (
+                    self.token is None
+                    or self.token == ""
+                    or self.is_token_expired(self.token)
+                ):
+                    self.logger.info("New token fetched for accessing organization API")
+                    self.token = self.token_manager.fetch_access_token()
+
+    def is_token_expired(self, token):
+        try:
+            decoded = jwt.decode(token, options={"verify_signature": False})
+            exp = decoded.get("exp")
+
+            if exp is None:
+                return True  # No expiration time present, consider it expired
+
+            # Check if the expiration time has passed
+            return datetime.fromtimestamp(exp) < datetime.utcnow()
+
+        except jwt.DecodeError:
+            return True  # Token is invalid
+        except Exception as e:
+            print(f"An error occurred: {e}")
+            return True

twilio/base/client_base.py

@@ -4,10 +4,10 @@
 from urllib.parse import urlparse, urlunparse
 
 from twilio import __version__
-from twilio.base.exceptions import TwilioException
 from twilio.http import HttpClient
 from twilio.http.http_client import TwilioHttpClient
 from twilio.http.response import Response
+from twilio.credential.credential_provider import CredentialProvider
 
 
 class ClientBase(object):
@@ -23,6 +23,7 @@ def __init__(
         environment: Optional[MutableMapping[str, str]] = None,
         edge: Optional[str] = None,
         user_agent_extensions: Optional[List[str]] = None,
+        credential_provider: Optional[CredentialProvider] = None,
     ):
         """
         Initializes the Twilio Client
@@ -35,7 +36,9 @@ def __init__(
         :param environment: Environment to look for auth details, defaults to os.environ
         :param edge: Twilio Edge to make requests to, defaults to None
         :param user_agent_extensions: Additions to the user agent string
+        :param credential_provider: credential provider for authentication method that needs to be used
         """
+
         environment = environment or os.environ
 
         self.username = username or environment.get("TWILIO_ACCOUNT_SID")
@@ -48,9 +51,8 @@ def __init__(
         """ :type : str """
         self.user_agent_extensions = user_agent_extensions or []
         """ :type : list[str] """
-
-        if not self.username or not self.password:
-            raise TwilioException("Credentials are required to create a TwilioClient")
+        self.credential_provider = credential_provider or None
+        """ :type : CredentialProvider """
 
         self.account_sid = account_sid or self.username
         """ :type : str """
@@ -85,15 +87,27 @@ def request(
 
         :returns: Response from the Twilio API
         """
-        auth = self.get_auth(auth)
         headers = self.get_headers(method, headers)
-        uri = self.get_hostname(uri)
 
+        if self.credential_provider:
+
+            auth_strategy = self.credential_provider.to_auth_strategy()
+            headers["Authorization"] = auth_strategy.get_auth_string()
+        elif self.username is not None and self.password is not None:
+            auth = self.get_auth(auth)
+        else:
+            auth = None
+
+        if method == "DELETE":
+            del headers["Accept"]
+
+        uri = self.get_hostname(uri)
+        filtered_data = self.copy_non_none_values(data)
         return self.http_client.request(
             method,
             uri,
             params=params,
-            data=data,
+            data=filtered_data,
             headers=headers,
             auth=auth,
             timeout=timeout,
@@ -132,21 +146,44 @@ async def request_async(
                 "http_client must be asynchronous to support async API requests"
             )
 
-        auth = self.get_auth(auth)
         headers = self.get_headers(method, headers)
-        uri = self.get_hostname(uri)
+        if method == "DELETE":
+            del headers["Accept"]
+
+        if self.credential_provider:
+            auth_strategy = self.credential_provider.to_auth_strategy()
+            headers["Authorization"] = auth_strategy.get_auth_string()
+        elif self.username is not None and self.password is not None:
+            auth = self.get_auth(auth)
+        else:
+            auth = None
 
+        uri = self.get_hostname(uri)
+        filtered_data = self.copy_non_none_values(data)
         return await self.http_client.request(
             method,
             uri,
             params=params,
-            data=data,
+            data=filtered_data,
             headers=headers,
             auth=auth,
             timeout=timeout,
             allow_redirects=allow_redirects,
         )
 
+    def copy_non_none_values(self, data):
+        if isinstance(data, dict):
+            return {
+                k: self.copy_non_none_values(v)
+                for k, v in data.items()
+                if v is not None
+            }
+        elif isinstance(data, list):
+            return [
+                self.copy_non_none_values(item) for item in data if item is not None
+            ]
+        return data
+
     def get_auth(self, auth: Optional[Tuple[str, str]]) -> Tuple[str, str]:
         """
         Get the request authentication object

twilio/base/page.py

@@ -77,6 +77,8 @@ def load_page(self, payload: Dict[str, Any]):
             key = keys - self.META_KEYS
             if len(key) == 1:
                 return payload[key.pop()]
+            if "Resources" in payload:
+                return payload["Resources"]
 
         raise TwilioException("Page Records can not be deserialized")
 

twilio/base/version.py

@@ -164,7 +164,6 @@ async def fetch_async(
             timeout=timeout,
             allow_redirects=allow_redirects,
         )
-
         return self._parse_fetch(method, uri, response)
 
     def _parse_update(self, method: str, uri: str, response: Response) -> Any:
@@ -461,7 +460,6 @@ def create(
             timeout=timeout,
             allow_redirects=allow_redirects,
         )
-
         return self._parse_create(method, uri, response)
 
     async def create_async(
@@ -488,5 +486,4 @@ async def create_async(
             timeout=timeout,
             allow_redirects=allow_redirects,
         )
-
         return self._parse_create(method, uri, response)

twilio/credential/client_credential_provider.py

@@ -0,0 +1,28 @@
+from twilio.http.orgs_token_manager import OrgTokenManager
+from twilio.base.exceptions import TwilioException
+from twilio.credential.credential_provider import CredentialProvider
+from twilio.auth_strategy.auth_type import AuthType
+from twilio.auth_strategy.token_auth_strategy import TokenAuthStrategy
+
+
+class ClientCredentialProvider(CredentialProvider):
+    def __init__(self, client_id: str, client_secret: str, token_manager=None):
+        super().__init__(AuthType.CLIENT_CREDENTIALS)
+
+        if client_id is None or client_secret is None:
+            raise TwilioException("Client id and Client secret are mandatory")
+
+        self.grant_type = "client_credentials"
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.token_manager = token_manager
+        self.auth_strategy = None
+
+    def to_auth_strategy(self):
+        if self.token_manager is None:
+            self.token_manager = OrgTokenManager(
+                self.grant_type, self.client_id, self.client_secret
+            )
+        if self.auth_strategy is None:
+            self.auth_strategy = TokenAuthStrategy(self.token_manager)
+        return self.auth_strategy

twilio/credential/credential_provider.py

@@ -0,0 +1,13 @@
+from twilio.auth_strategy.auth_type import AuthType
+
+
+class CredentialProvider:
+    def __init__(self, auth_type: AuthType):
+        self._auth_type = auth_type
+
+    @property
+    def auth_type(self) -> AuthType:
+        return self._auth_type
+
+    def to_auth_strategy(self):
+        raise NotImplementedError("Subclasses must implement this method")