Added credential provider factory methods

Author: vladvildanov

README.md

@@ -1,4 +1,4 @@
-The `redis-entra-id` Python package helps simplifying the authentication with [Azure Managed Redis](https://azure.microsoft.com/en-us/products/managed-redis) and Azure Cache for Redis using Microsoft Entra ID (formerly Azure Active Directory). It enables seamless integration with Azure's Redis services by fetching authentication tokens and managing the token renewal in the background. This package builds on top of `redis-py` and provides a structured way to authenticate by using a:
+from redis.auth.token_manager import RetryPolicyThe `redis-entra-id` Python package helps simplifying the authentication with [Azure Managed Redis](https://azure.microsoft.com/en-us/products/managed-redis) and Azure Cache for Redis using Microsoft Entra ID (formerly Azure Active Directory). It enables seamless integration with Azure's Redis services by fetching authentication tokens and managing the token renewal in the background. This package builds on top of `redis-py` and provides a structured way to authenticate by using a:
 
 * System-assigned managed identity
 * User-assigned managed identity
@@ -35,7 +35,7 @@ You need to install the `redis-py` Entra ID package via the following command:
 pip install redis-entra-id
 ```
 
-The package depends on [redis-py](https://github.com/redis/redis-py/tree/v5.3.0b4) version `5.3.0b4`.
+The package depends on [redis-py](https://github.com/redis/redis-py).
 
 ## Usage
 
@@ -45,31 +45,38 @@ After having installed the package, you can import its modules:
 
 ```python
 import redis
-from redis_entraid import identity_provider
 from redis_entraid import cred_provider
 ```
 
-### Step 2 - Define your authority based on the tenant ID
+### Step 2 - Create the credential provider via the factory method
 
 ```python
-authority = "{}/{}".format("https://login.microsoftonline.com", "<TENANT_ID>")
+cred_provider = create_from_service_principal(
+    client_credential="<CLIENT_SECRET>", 
+    client_id="<CLIENT_ID>", 
+    tenant_id="<TENANT_ID>"
+)
 ```
 
-> This step is going to be removed in the next pre-release version of `redis-py-entraid`. Instead, the factory method will allow to pass the tenant id direclty.
+### Step 3 - Provide optional token renewal configuration
 
-### Step 3 - Create the identity provider via the factory method
-
-```python
-idp = identity_provider.create_provider_from_service_principal("<CLIENT_SECRET>", "<CLIENT_ID>", authority=authority)
-```
-
-### Step 4 - Initialize a credentials provider from the authentication configuration
-
-You can use the default configuration or customize the background task for token renewal.
+The default configuration would be applied, but you're able to customise it.
 
 ```python
-auth_config = TokenAuthConfig(idp)
-cred_provider = EntraIdCredentialsProvider(auth_config)
+cred_provider = create_from_service_principal(
+    client_credential="<CLIENT_SECRET>", 
+    client_id="<CLIENT_ID>", 
+    tenant_id="<TENANT_ID>",
+    token_manager_config=TokenManagerConfig(
+        expiration_refresh_ratio=0.9,
+        lower_refresh_bound_millis=DEFAULT_LOWER_REFRESH_BOUND_MILLIS,
+        token_request_execution_timeout_in_ms=DEFAULT_TOKEN_REQUEST_EXECUTION_TIMEOUT_IN_MS,
+        retry_policy=RetryPolicy(
+            max_attempts=5,
+            delay_in_ms=50
+        )
+    )
+)
 ```
 
 You can test the credentials provider by obtaining a token. The following example demonstrates both, a synchronous and an asynchronous approach:
@@ -82,7 +89,7 @@ cred_provider.get_credentials()
 await cred_provider.get_credentials_async()
 ```
 
-### Step 5 - Connect to Redis
+### Step 4 - Connect to Redis
 
 When using Entra ID, Azure enforces TLS on your Redis connection. Here is an example that shows how to **test** the connection in an insecure way:
 

redis_entraid/cred_provider.py

@@ -1,70 +1,50 @@
-from dataclasses import dataclass
-from typing import Union, Tuple, Callable, Any, Awaitable
+from typing import Union, Tuple, Callable, Any, Awaitable, Optional
 
 from redis.credentials import StreamingCredentialProvider
 from redis.auth.token_manager import TokenManagerConfig, RetryPolicy, TokenManager, CredentialsListener
 
-from redis_entraid.identity_provider import EntraIDIdentityProvider
-
-
-@dataclass
-class TokenAuthConfig:
-    """
-    Configuration for token authentication.
-
-    Requires :class:`EntraIDIdentityProvider`. It's recommended to use an additional factory methods.
-    See :class:`EntraIDIdentityProvider` for more information.
-    """
-    DEFAULT_EXPIRATION_REFRESH_RATIO = 0.8
-    DEFAULT_LOWER_REFRESH_BOUND_MILLIS = 0
-    DEFAULT_TOKEN_REQUEST_EXECUTION_TIMEOUT_IN_MS = 100
-    DEFAULT_MAX_ATTEMPTS = 3
-    DEFAULT_DELAY_IN_MS = 3
-
-    idp: EntraIDIdentityProvider
-    expiration_refresh_ratio: float = DEFAULT_EXPIRATION_REFRESH_RATIO
-    lower_refresh_bound_millis: int = DEFAULT_LOWER_REFRESH_BOUND_MILLIS
-    token_request_execution_timeout_in_ms: int = DEFAULT_TOKEN_REQUEST_EXECUTION_TIMEOUT_IN_MS
-    max_attempts: int = DEFAULT_MAX_ATTEMPTS
-    delay_in_ms: int = DEFAULT_DELAY_IN_MS
-
-    def get_token_manager_config(self) -> TokenManagerConfig:
-        return TokenManagerConfig(
-            self.expiration_refresh_ratio,
-            self.lower_refresh_bound_millis,
-            self.token_request_execution_timeout_in_ms,
-            RetryPolicy(
-                self.max_attempts,
-                self.delay_in_ms
-            )
-        )
-
-    def get_identity_provider(self) -> EntraIDIdentityProvider:
-        return self.idp
+from redis_entraid.identity_provider import ManagedIdentityType, ManagedIdentityIdType, \
+    create_provider_from_managed_identity, ManagedIdentityProviderConfig, ServicePrincipalIdentityProviderConfig, \
+    create_provider_from_service_principal
 
+DEFAULT_EXPIRATION_REFRESH_RATIO = 0.7
+DEFAULT_LOWER_REFRESH_BOUND_MILLIS = 0
+DEFAULT_TOKEN_REQUEST_EXECUTION_TIMEOUT_IN_MS = 100
+DEFAULT_MAX_ATTEMPTS = 3
+DEFAULT_DELAY_IN_MS = 3
 
 class EntraIdCredentialsProvider(StreamingCredentialProvider):
     def __init__(
             self,
-            config: TokenAuthConfig,
+            idp_config: Union[ManagedIdentityProviderConfig, ServicePrincipalIdentityProviderConfig],
+            token_manager_config: TokenManagerConfig,
             initial_delay_in_ms: float = 0,
             block_for_initial: bool = False,
     ):
         """
-        :param config:
+        :param idp_config: Identity provider specific configuration.
+        :param token_manager_config: Token manager specific configuration.
         :param initial_delay_in_ms: Initial delay before run background refresh (valid for async only)
         :param block_for_initial: Block execution until initial token will be acquired (valid for async only)
         """
+        if isinstance(idp_config, ManagedIdentityProviderConfig):
+            idp = create_provider_from_managed_identity(idp_config)
+        else:
+            idp = create_provider_from_service_principal(idp_config)
+
         self._token_mgr = TokenManager(
-            config.get_identity_provider(),
-            config.get_token_manager_config()
+            idp,
+            token_manager_config
         )
         self._listener = CredentialsListener()
         self._is_streaming = False
         self._initial_delay_in_ms = initial_delay_in_ms
         self._block_for_initial = block_for_initial
 
     def get_credentials(self) -> Union[Tuple[str], Tuple[str, str]]:
+        """
+        Acquire token from the identity provider.
+        """
         init_token = self._token_mgr.acquire_token()
 
         if self._is_streaming is False:
@@ -77,6 +57,9 @@ def get_credentials(self) -> Union[Tuple[str], Tuple[str, str]]:
         return init_token.get_token().try_get('oid'), init_token.get_token().get_value()
 
     async def get_credentials_async(self) -> Union[Tuple[str], Tuple[str, str]]:
+        """
+        Acquire token from the identity provider in async mode.
+        """
         init_token = await self._token_mgr.acquire_token_async()
 
         if self._is_streaming is False:
@@ -98,3 +81,85 @@ def on_error(self, callback: Union[Callable[[Exception], None], Awaitable]):
 
     def is_streaming(self) -> bool:
         return self._is_streaming
+
+
+def create_from_managed_identity(
+        identity_type: ManagedIdentityType,
+        resource: str,
+        id_type: Optional[ManagedIdentityIdType] = None,
+        id_value: Optional[str] = '',
+        kwargs: Optional[dict] = None,
+        token_manager_config: Optional[TokenManagerConfig] = TokenManagerConfig(
+            DEFAULT_EXPIRATION_REFRESH_RATIO,
+            DEFAULT_LOWER_REFRESH_BOUND_MILLIS,
+            DEFAULT_TOKEN_REQUEST_EXECUTION_TIMEOUT_IN_MS,
+            RetryPolicy(
+                DEFAULT_MAX_ATTEMPTS,
+                DEFAULT_DELAY_IN_MS
+            )
+        )
+) -> EntraIdCredentialsProvider:
+    """
+    Create a credential provider from a managed identity type.
+
+    :param identity_type: Managed identity type.
+    :param resource: Identity provider resource.
+    :param id_type: Identity provider type.
+    :param id_value: Identity provider value.
+    :param kwargs: Optional keyword arguments to pass to identity provider. See: :class:`ManagedIdentityClient`
+    :param token_manager_config: Token manager specific configuration.
+    :return: EntraIdCredentialsProvider instance.
+    """
+    managed_identity_config = ManagedIdentityProviderConfig(
+        identity_type=identity_type,
+        resource=resource,
+        id_type=id_type,
+        id_value=id_value,
+        kwargs=kwargs
+    )
+
+    return EntraIdCredentialsProvider(managed_identity_config, token_manager_config)
+
+
+def create_from_service_principal(
+        client_credential: Any,
+        client_id: str,
+        scopes: Optional[list[str]] = None,
+        timeout: Optional[float] = None,
+        tenant_id: Optional[str] = None,
+        token_kwargs: Optional[dict] = None,
+        app_kwargs: Optional[dict] = None,
+        token_manager_config: Optional[TokenManagerConfig] = TokenManagerConfig(
+            DEFAULT_EXPIRATION_REFRESH_RATIO,
+            DEFAULT_LOWER_REFRESH_BOUND_MILLIS,
+            DEFAULT_TOKEN_REQUEST_EXECUTION_TIMEOUT_IN_MS,
+            RetryPolicy(
+                DEFAULT_MAX_ATTEMPTS,
+                DEFAULT_DELAY_IN_MS
+            )
+        )
+) -> EntraIdCredentialsProvider:
+    """
+    Create a credential provider from a service principal.
+
+    :param client_credential: Service principal credentials.
+    :param client_id: Service principal client ID.
+    :param scopes: Service principal scopes. Fallback to default scopes if None.
+    :param timeout: Service principal timeout.
+    :param tenant_id: Service principal tenant ID.
+    :param token_kwargs: Optional token arguments to pass to service identity provider.
+    :param app_kwargs: Optional keyword arguments to pass to service principal application.
+    :param token_manager_config: Token manager specific configuration.
+    :return: EntraIdCredentialsProvider instance.
+    """
+    service_principal_config = ServicePrincipalIdentityProviderConfig(
+        client_credential=client_credential,
+        client_id=client_id,
+        scopes=scopes,
+        timeout=timeout,
+        tenant_id=tenant_id,
+        app_kwargs=app_kwargs,
+        token_kwargs=token_kwargs,
+    )
+
+    return EntraIdCredentialsProvider(service_principal_config, token_manager_config)

redis_entraid/identity_provider.py

@@ -1,5 +1,6 @@
+from dataclasses import dataclass
 from enum import Enum
-from typing import Optional, Union, Callable
+from typing import Optional, Union, Callable, Any
 
 import requests
 from msal import (
@@ -24,6 +25,26 @@ class ManagedIdentityIdType(Enum):
     RESOURCE_ID = "resource_id"
 
 
+@dataclass
+class ManagedIdentityProviderConfig:
+    identity_type: ManagedIdentityType
+    resource: str
+    id_type: Optional[ManagedIdentityIdType] = None
+    id_value: Optional[str] = ''
+    kwargs: Optional[dict] = None
+
+
+@dataclass
+class ServicePrincipalIdentityProviderConfig:
+    client_credential: Any
+    client_id: str
+    scopes: Optional[list[str]] = None
+    timeout: Optional[float] = None
+    tenant_id: Optional[str] = None
+    token_kwargs: Optional[dict] = None
+    app_kwargs: Optional[dict] = None
+
+
 class EntraIDIdentityProvider(IdentityProviderInterface):
     """
     EntraID Identity Provider implementation.
@@ -75,70 +96,54 @@ def _get_token(self, callback: Callable, **kwargs) -> JWToken:
             raise RequestTokenErr(e)
 
 
-def create_provider_from_managed_identity(
-        identity_type: ManagedIdentityType,
-        resource: str,
-        id_type: Optional[ManagedIdentityIdType] = None,
-        id_value: Optional[str] = '',
-        **kwargs
-) -> EntraIDIdentityProvider:
+def create_provider_from_managed_identity(config: ManagedIdentityProviderConfig) -> EntraIDIdentityProvider:
     """
     Create an EntraID identity provider following Managed Identity auth flow.
 
-    :param identity_type: User Assigned or System Assigned.
-    :param resource: Resource for which token should be acquired.
-    :param id_type: Required for User Assigned identity type only.
-    :param id_value: Required for User Assigned identity type only.
-    :param kwargs: Additional arguments you may need during specify to request token.
+    :param config: Config for managed assigned identity provider
     See: :class:`ManagedIdentityClient` acquire_token_for_client method.
 
     :return: :class:`EntraIDIdentityProvider`
     """
-    if identity_type == ManagedIdentityType.USER_ASSIGNED:
-        if id_type is None or id_value == '':
+    if config.identity_type == ManagedIdentityType.USER_ASSIGNED:
+        if config.id_type is None or config.id_value == '':
             raise ValueError("Id_type and id_value are required for User Assigned identity auth")
 
         kwargs = {
-            id_type.value: id_value
+            config.id_type.value: config.id_value
         }
 
-        managed_identity = identity_type.value(**kwargs)
+        managed_identity = config.identity_type.value(**kwargs)
     else:
-        managed_identity = identity_type.value()
+        managed_identity = config.identity_type.value()
 
     app = ManagedIdentityClient(managed_identity, http_client=requests.Session())
-    return EntraIDIdentityProvider(app, [], resource, **kwargs)
+    return EntraIDIdentityProvider(app, [], config.resource, **config.kwargs)
 
 
-def create_provider_from_service_principal(
-        client_credential,
-        client_id: str,
-        scopes: list = [],
-        timeout: Optional[float] = None,
-        token_kwargs: dict = {},
-        **app_kwargs
-) -> EntraIDIdentityProvider:
+def create_provider_from_service_principal(config: ServicePrincipalIdentityProviderConfig) -> EntraIDIdentityProvider:
     """
     Create an EntraID identity provider following Service Principal auth flow.
 
-    :param client_credential: Can be secret string, PEM certificate and more.
-    See: :class:`ConfidentialClientApplication`.
+    :param config: Config for service principal identity provider
 
-    :param client_id: Application (Client) ID.
-    :param scopes: If no scopes will be provided, default will be used.
-    :param timeout: Timeout in seconds.
-    :param token_kwargs: Additional arguments you may need during token request.
-    :param app_kwargs: Additional arguments you may need to configure an application.
     :return: :class:`EntraIDIdentityProvider`
+    See: :class:`ConfidentialClientApplication`.
     """
 
-    if len(scopes) == 0:
-        scopes.append("https://redis.azure.com/.default")
+    if config.scopes is None:
+        scopes = ["https://redis.azure.com/.default"]
+    else:
+        scopes = config.scopes
+
+    authority = f"https://login.microsoftonline.com/{config.tenant_id}" \
+        if config.tenant_id is not None else config.tenant_id
 
     app = ConfidentialClientApplication(
-        client_id=client_id,
-        client_credential=client_credential,
-        timeout=timeout,
-        **app_kwargs
+        client_id=config.client_id,
+        client_credential=config.client_credential,
+        timeout=config.timeout,
+        authority=authority,
+        **config.app_kwargs
     )
-    return EntraIDIdentityProvider(app, scopes, **token_kwargs)
+    return EntraIDIdentityProvider(app, scopes, **config.token_kwargs)