Intial commit for adding support for other authentication strategies

Author: mridang

zitadel_client/auth/authenticator.py

@@ -1,65 +1,77 @@
 from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Dict
+
+from zitadel_client.auth.open_id import OpenId
 
 
 class Authenticator(ABC):
   """
-  Abstract base class for authentication strategies.
-
-  This class defines a common interface for implementing various
-  authentication mechanisms. Subclasses must implement the
-  `get_auth_headers` method to provide the necessary HTTP headers for
-  authenticated API requests, as well as the `refresh_token` method for
-  refreshing authentication tokens when needed.
+  Abstract base class for authenticators.
 
-  Attributes:
-      host (str): The base URL for authentication endpoints.
+  This class defines the basic structure for any authenticator by requiring the implementation
+  of a method to retrieve authentication headers, and provides a way to store and retrieve the host.
   """
 
   def __init__(self, host: str):
     """
-    Initialize the Authenticator with a host URL.
+    Initializes the Authenticator with the specified host.
 
-    Args:
-        host (str): The base URL for all authentication endpoints.
+    :param host: The base URL or endpoint for the service.
     """
     self.host = host
 
   @abstractmethod
-  def get_auth_headers(self) -> dict[str, str]:
+  def get_auth_headers(self) -> Dict[str, str]:
     """
-    Generate and return the authentication headers required for API requests.
+    Retrieves the authentication headers to be sent with requests.
 
-    Subclasses must implement this method to return a dictionary where the keys
-    are the header names and the values are the corresponding header values.
+    Subclasses must override this method to return the appropriate headers.
 
-    Returns:
-        dict[str, str]: A dictionary containing the authentication header(s).
+    :return: A dictionary mapping header names to their values.
     """
     pass
 
-  @abstractmethod
-  def refresh_token(self) -> None:
+  def get_host(self) -> str:
+    """
+    Returns the stored host.
+
+    :return: The host as a string.
     """
-    Refresh the authentication token.
+    return self.host
+
+
+class Token:
+  def __init__(self, access_token: str, expires_at: datetime):
+    self.access_token = access_token
+    self.expires_at = expires_at
+
+  def is_expired(self) -> bool:
+    return datetime.now(timezone.utc) >= self.expires_at
 
-    This abstract method must be implemented by subclasses that require a mechanism
-    to refresh the authentication token. The implementation should update the token
-    used by the authenticator.
 
-    Returns:
-        None
+class OAuthAuthenticatorBuilder(ABC):
+  """
+  Abstract builder class for constructing OAuth authenticator instances.
+
+  This builder provides common configuration options such as the OpenId instance and authentication scopes.
+  """
+
+  def __init__(self, host: str):
     """
-    pass
+    Initializes the OAuthAuthenticatorBuilder with a given host.
 
-  def get_host(self) -> str:
+    :param host: The base URL for the OAuth provider.
     """
-    Retrieve the base host URL.
+    self.open_id = OpenId(host)
+    self.auth_scopes = "openid urn:zitadel:iam:org:project:id:zitadel:aud"
 
-    This method returns the host URL that was specified during the instantiation
-    of the Authenticator. It can be used by concrete classes or external consumers
-    to build full endpoint URLs.
+  def scopes(self, auth_scopes: set) -> "OAuthAuthenticatorBuilder":
+    """
+    Sets the authentication scopes for the OAuth authenticator.
 
-    Returns:
-        str: The base URL for authentication endpoints.
+    :param auth_scopes: A set of scope strings.
+    :return: The builder instance to allow for method chaining.
     """
-    return self.host
+    self.auth_scopes = " ".join(auth_scopes)
+    return self

zitadel_client/auth/client_credentials.py

@@ -0,0 +1,81 @@
+from typing import override
+
+from authlib.integrations.requests_client import OAuth2Session
+
+from zitadel_client.auth.authenticator import OAuthAuthenticatorBuilder
+from zitadel_client.auth.oauth_authenticator import OAuthAuthenticator
+from zitadel_client.auth.open_id import OpenId
+
+
+class ClientCredentialsAuthenticator(OAuthAuthenticator):
+  """
+  OAuth authenticator implementing the client credentials flow.
+
+  Uses client_id and client_secret to obtain an access token from the OAuth2 token endpoint.
+  """
+
+  def __init__(self, open_id: OpenId, client_id: str, client_secret: str, auth_scopes: str):
+    """
+    Constructs a ClientCredentialsAuthenticator.
+
+    :param open_id: The base URL for the OAuth provider.
+    :param client_id: The OAuth client identifier.
+    :param client_secret: The OAuth client secret.
+    :param auth_scopes: The scope(s) for the token request.
+    """
+    super().__init__(open_id, OAuth2Session(client_id=client_id, client_secret=client_secret, scope=auth_scopes))
+
+  @override
+  def get_grant(self) -> dict:
+    """
+    Returns the grant parameters for the client credentials flow.
+
+    :return: A dictionary with the grant type for client credentials.
+    """
+    return {"grant_type": "client_credentials"}
+
+  @staticmethod
+  def builder(host: str, client_id: str, client_secret: str) -> "ClientCredentialsAuthenticatorBuilder":
+    """
+    Returns a builder for constructing a ClientCredentialsAuthenticator.
+
+    :param host: The base URL for the OAuth provider.
+    :param client_id: The OAuth client identifier.
+    :param client_secret: The OAuth client secret.
+    :return: A ClientCredentialsAuthenticatorBuilder instance.
+    """
+    return ClientCredentialsAuthenticatorBuilder(host, client_id, client_secret)
+
+
+class ClientCredentialsAuthenticatorBuilder(OAuthAuthenticatorBuilder):
+  """
+  Builder class for constructing ClientCredentialsAuthenticator instances.
+
+  This builder extends the OAuthAuthenticatorBuilder with client credentials (client_id and client_secret)
+  required for the client credentials flow.
+  """
+
+  def __init__(self, host: str, client_id: str, client_secret: str):
+    """
+    Initializes the ClientCredentialsAuthenticatorBuilder with host, client ID, and client secret.
+
+    :param host: The base URL for the OAuth provider.
+    :param client_id: The OAuth client identifier.
+    :param client_secret: The OAuth client secret.
+    """
+    super().__init__(host)
+    self.client_id = client_id
+    self.client_secret = client_secret
+
+  def build(self) -> ClientCredentialsAuthenticator:
+    """
+    Constructs and returns a ClientCredentialsAuthenticator instance using the configured parameters.
+
+    :return: A configured ClientCredentialsAuthenticator.
+    """
+    return ClientCredentialsAuthenticator(
+      self.open_id,  # OpenId instance with endpoint info (constructed from host)
+      self.client_id,  # OAuth client identifier
+      self.client_secret,  # OAuth client secret
+      self.auth_scopes  # Authentication scopes configured in the builder
+    )