auth0-api-python 1.0.0b6__py3-none-any.whl → 1.0.0b8__py3-none-any.whl

auth0_api_python/__init__.py

@@ -6,12 +6,25 @@ in server-side APIs, using Authlib for OIDC discovery and JWKS fetching.
 """
 
 from .api_client import ApiClient
+from .cache import CacheAdapter, InMemoryCache
 from .config import ApiClientOptions
-from .errors import ApiError, GetTokenByExchangeProfileError
+from .errors import (
+    ApiError,
+    ConfigurationError,
+    DomainsResolverError,
+    GetTokenByExchangeProfileError,
+)
+from .types import DomainsResolver, DomainsResolverContext
 
 __all__ = [
     "ApiClient",
     "ApiClientOptions",
     "ApiError",
-    "GetTokenByExchangeProfileError"
+    "CacheAdapter",
+    "ConfigurationError",
+    "DomainsResolver",
+    "DomainsResolverContext",
+    "DomainsResolverError",
+    "GetTokenByExchangeProfileError",
+    "InMemoryCache",
 ]

auth0_api_python/api_client.py

@@ -1,3 +1,4 @@
+import asyncio
 import time
 from collections.abc import Mapping, Sequence
 from typing import Any, Optional, Union
@@ -5,10 +6,13 @@ from typing import Any, Optional, Union
 import httpx
 from authlib.jose import JsonWebKey, JsonWebToken
 
+from .cache import InMemoryCache
 from .config import ApiClientOptions
 from .errors import (
     ApiError,
     BaseAuthError,
+    ConfigurationError,
+    DomainsResolverError,
     GetAccessTokenForConnectionError,
     GetTokenByExchangeProfileError,
     InvalidAuthSchemeError,
@@ -22,6 +26,8 @@ from .utils import (
     fetch_jwks,
     fetch_oidc_metadata,
     get_unverified_header,
+    get_unverified_payload,
+    normalize_domain,
     normalize_url_for_htu,
     sha256_base64url,
 )
@@ -48,14 +54,62 @@ class ApiClient:
     """
 
     def __init__(self, options: ApiClientOptions):
-        if not options.domain:
-            raise MissingRequiredArgumentError("domain")
+        # Validate audience is always required
         if not options.audience:
             raise MissingRequiredArgumentError("audience")
 
+        # Validate domains parameter if provided
+        if options.domains is not None:
+            if isinstance(options.domains, list):
+                # Static list validation
+                if len(options.domains) == 0:
+                    raise ConfigurationError("domains list cannot be empty")
+                if not all(isinstance(d, str) and d.strip() for d in options.domains):
+                    raise ConfigurationError(
+                        "domains list must contain only non-empty strings"
+                    )
+                # Normalize and store domains
+                self._allowed_domains = [normalize_domain(d) for d in options.domains]
+            elif callable(options.domains):
+                # Dynamic resolver - store the function
+                self._allowed_domains = options.domains
+            else:
+                raise ConfigurationError(
+                    "domains must be either a list of domain strings or a callable resolver function"
+                )
+        else:
+            # Single domain mode
+            self._allowed_domains = None
+
+        # Validate domain/domains configuration
+        if not options.domain and not options.domains:
+            raise ConfigurationError(
+                "Must provide either 'domain' or 'domains' parameter. "
+                "Use 'domain' for single-domain mode, 'domains' for multi-domain support."
+            )
+
+        # Validate that domain is set when client_id is configured
+        if options.client_id and not options.domain:
+            raise ConfigurationError(
+                "The 'domain' parameter is required when 'client_id' is configured."
+            )
         self.options = options
-        self._metadata: Optional[dict[str, Any]] = None
-        self._jwks_data: Optional[dict[str, Any]] = None
+
+        # Validate cache configuration
+        if not isinstance(options.cache_ttl_seconds, (int, float)) or options.cache_ttl_seconds < 0:
+            raise ConfigurationError("cache_ttl_seconds must be a non-negative number")
+
+        if not isinstance(options.cache_max_entries, int) or options.cache_max_entries < 2:
+            raise ConfigurationError("cache_max_entries must be an integer greater than 1")
+
+        if options.cache_adapter:
+            self._discovery_cache = options.cache_adapter
+            self._jwks_cache = options.cache_adapter
+        else:
+            self._discovery_cache = InMemoryCache(max_entries=options.cache_max_entries)
+            self._jwks_cache = InMemoryCache(max_entries=options.cache_max_entries)
+
+        self._cache_ttl = options.cache_ttl_seconds
 
         self._jwt = JsonWebToken(["RS256"])
 
@@ -66,6 +120,92 @@ class ApiClient:
         """Check if DPoP authentication is required."""
         return getattr(self.options, "dpop_required", False)
 
+    async def _resolve_allowed_domains(
+        self,
+        unverified_iss: str,
+        request_url: Optional[str] = None,
+        request_headers: Optional[dict] = None
+    ) -> Optional[list[str]]:
+        """
+        Resolve and validate allowed domains for the given issuer.
+
+        Handles three modes:
+        1. Static list: Returns normalized list, validates issuer against it
+        2. Dynamic resolver: Invokes resolver function, validates issuer against result
+        3. Single domain: Returns None (backward compatibility, uses domain)
+
+        Args:
+            unverified_iss: The issuer claim from the token (not yet verified)
+            request_url: Optional request URL for dynamic resolvers
+            request_headers: Optional request headers for dynamic resolvers
+
+        Returns:
+            List of normalized allowed domain strings
+
+        Raises:
+            DomainsResolverError: If resolver invocation fails
+            VerifyAccessTokenError: If issuer is not in allowed domains
+        """
+        # Single domain mode
+        if self._allowed_domains is None:
+            return None
+
+        # Static list mode
+        if isinstance(self._allowed_domains, list):
+            allowed_domains = self._allowed_domains
+        # Dynamic resolver mode
+        elif callable(self._allowed_domains):
+            # Build resolver context
+            context = {
+                'request_url': request_url,
+                'request_headers': request_headers,
+                'unverified_iss': unverified_iss
+            }
+
+            # Invoke resolver (supports both sync and async resolvers)
+            try:
+                result = self._allowed_domains(context)
+                if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                    result = await result
+            except Exception as e:
+                raise DomainsResolverError(
+                    f"Domains resolver function failed: {str(e)}"
+                ) from e
+
+            # Validate resolver result
+            if not isinstance(result, list):
+                raise DomainsResolverError(
+                    "Domains resolver must return a list"
+                )
+
+            if len(result) == 0:
+                raise DomainsResolverError(
+                    "Domains resolver returned an empty list"
+                )
+
+            if not all(isinstance(d, str) and d.strip() for d in result):
+                raise DomainsResolverError(
+                    "Domains resolver must return a list of non-empty strings"
+                )
+
+            # Normalize domains from resolver
+            try:
+                allowed_domains = [normalize_domain(d) for d in result]
+            except ValueError as e:
+                raise DomainsResolverError(
+                    f"Domains resolver returned invalid domain: {str(e)}"
+                ) from e
+        else:
+            # Should never happen due to __init__ validation
+            raise ConfigurationError("Invalid _allowed_domains type")
+
+        # Validate issuer is in allowed domains
+        if unverified_iss not in allowed_domains:
+            raise VerifyAccessTokenError(
+                "Token issuer is not in the list of allowed domains"
+            )
+
+        return allowed_domains
 
     async def verify_request(
         self,
@@ -89,7 +229,7 @@ class ApiClient:
                 - "authorization": The Authorization header value (required)
                 - "dpop": The DPoP proof header value (required for DPoP)
             http_method: The HTTP method (required for DPoP)
-            http_url: The HTTP URL (required for DPoP)
+            http_url: The HTTP URL (required for DPoP, also used for MCD resolver context)
 
         Returns:
             The decoded access token claims
@@ -171,7 +311,11 @@ class ApiClient:
                 )
 
             try:
-                access_token_claims = await self.verify_access_token(token)
+                access_token_claims = await self.verify_access_token(
+                    token,
+                    request_url=http_url,
+                    request_headers=headers
+                )
             except VerifyAccessTokenError as e:
                 raise self._prepare_error(e, auth_scheme=scheme)
 
@@ -219,7 +363,11 @@ class ApiClient:
 
         if scheme == "bearer":
             try:
-                claims = await self.verify_access_token(token)
+                claims = await self.verify_access_token(
+                    token,
+                    request_url=http_url,
+                    request_headers=headers
+                )
                 if claims.get("cnf") and isinstance(claims["cnf"], dict) and claims["cnf"].get("jkt"):
                     if self.options.dpop_enabled:
                         raise self._prepare_error(
@@ -245,6 +393,8 @@ class ApiClient:
     async def verify_access_token(
         self,
         access_token: str,
+        request_url: Optional[str] = None,
+        request_headers: Optional[dict] = None,
         required_claims: Optional[list[str]] = None
     ) -> dict[str, Any]:
         """
@@ -255,25 +405,113 @@ class ApiClient:
         - Checks standard claims: 'iss', 'aud', 'exp', 'iat'
         - Checks extra required claims if 'required_claims' is provided.
 
+        Args:
+            access_token: The JWT access token to verify
+            request_url: Optional request URL for dynamic domain resolvers
+            request_headers: Optional request headers dict for dynamic domain resolvers
+            required_claims: Optional list of additional claim names that must be present
+
         Returns:
             The decoded token claims if valid.
 
         Raises:
             MissingRequiredArgumentError: If no token is provided.
             VerifyAccessTokenError: If verification fails (signature, claims mismatch, etc.).
+            DomainsResolverError: If domains resolver function fails.
         """
         if not access_token:
             raise MissingRequiredArgumentError("access_token")
 
         required_claims = required_claims or []
 
+        # Extract header and payload without signature verification
         try:
             header = get_unverified_header(access_token)
-            kid = header["kid"]
         except Exception as e:
             raise VerifyAccessTokenError(f"Failed to parse token header: {str(e)}") from e
 
-        jwks_data = await self._load_jwks()
+        # Reject symmetric algorithms
+        alg = header.get('alg', '')
+        if alg.startswith('HS'):
+            raise VerifyAccessTokenError(
+                f"Symmetric algorithm '{alg}' is not supported. "
+                "Only asymmetric algorithms (e.g., RS256) are allowed."
+            )
+
+        # Extract and validate issuer claim (before network calls)
+        try:
+            unverified_payload = get_unverified_payload(access_token)
+        except Exception as e:
+            raise VerifyAccessTokenError(f"Failed to parse token payload: {str(e)}") from e
+
+        unverified_iss = unverified_payload.get('iss')
+        if not unverified_iss:
+            raise VerifyAccessTokenError("Token missing 'iss' claim")
+
+        # Normalize issuer for validation
+        try:
+            normalized_iss = normalize_domain(unverified_iss)
+        except ValueError as e:
+            raise VerifyAccessTokenError(f"Invalid token issuer format: {str(e)}") from e
+
+        # Validate issuer against allowed domains (MCD)
+        if self._allowed_domains is not None:
+            await self._resolve_allowed_domains(
+                normalized_iss,
+                request_url=request_url,
+                request_headers=request_headers
+            )
+
+        # Fetch OIDC discovery metadata
+        try:
+            if self._allowed_domains is not None:
+                metadata = await self._discover(issuer=normalized_iss)
+            else:
+                metadata = await self._discover()
+        except VerifyAccessTokenError:
+            raise
+        except Exception as e:
+            raise VerifyAccessTokenError(
+                f"Failed to fetch OIDC discovery metadata: {str(e)}"
+            ) from e
+
+        # First issuer validation: Prevent issuer confusion attacks
+        discovery_issuer = metadata.get("issuer")
+        if not discovery_issuer:
+            raise VerifyAccessTokenError("Discovery metadata missing 'issuer' field")
+
+        # Normalize discovery issuer for comparison
+        try:
+            normalized_discovery_issuer = normalize_domain(discovery_issuer)
+        except ValueError as e:
+            raise VerifyAccessTokenError(f"Invalid discovery issuer format: {str(e)}") from e
+
+        if normalized_iss != normalized_discovery_issuer:
+            raise VerifyAccessTokenError(
+                "Token issuer does not match the discovery issuer"
+            )
+
+        # Extract JWKS URI from discovery metadata
+        jwks_uri = metadata.get("jwks_uri")
+        if not jwks_uri:
+            raise VerifyAccessTokenError("Discovery metadata missing 'jwks_uri' field")
+
+        # Fetch JWKS from discovery's jwks_uri
+        try:
+            jwks_data = await self._fetch_jwks(jwks_uri)
+        except VerifyAccessTokenError:
+            raise
+        except Exception as e:
+            raise VerifyAccessTokenError(
+                f"Failed to fetch JWKS: {str(e)}"
+            ) from e
+
+        # Extract kid for JWKS lookup
+        kid = header.get("kid")
+        if not kid:
+            raise VerifyAccessTokenError("Token header missing 'kid' claim")
+
+        # Find matching key
         matching_key_dict = None
         for key_dict in jwks_data["keys"]:
             if key_dict.get("kid") == kid:
@@ -281,8 +519,9 @@ class ApiClient:
                 break
 
         if not matching_key_dict:
-            raise VerifyAccessTokenError(f"No matching key found for kid: {kid}")
+            raise VerifyAccessTokenError("No matching key found in JWKS")
 
+        # Import public key and verify signature
         public_key = JsonWebKey.import_key(matching_key_dict)
 
         if isinstance(access_token, str) and access_token.startswith("b'"):
@@ -292,11 +531,11 @@ class ApiClient:
         except Exception as e:
             raise VerifyAccessTokenError(f"Signature verification failed: {str(e)}") from e
 
-        metadata = await self._discover()
-        issuer = metadata["issuer"]
-
-        if claims.get("iss") != issuer:
-            raise VerifyAccessTokenError("Issuer mismatch")
+        # Second issuer validation: Ensure verified token wasn't tampered
+        if claims.get("iss") != discovery_issuer:
+            raise VerifyAccessTokenError(
+                "Verified Token issuer does not match the discovery issuer"
+            )
 
         expected_aud = self.options.audience
         actual_aud = claims.get("aud")
@@ -767,25 +1006,73 @@ class ApiClient:
             else:
                 params[key] = str(v)
 
-    async def _discover(self) -> dict[str, Any]:
-        """Lazy-load OIDC discovery metadata."""
-        if self._metadata is None:
-            self._metadata = await fetch_oidc_metadata(
-                domain=self.options.domain,
-                custom_fetch=self.options.custom_fetch
-            )
-        return self._metadata
-
-    async def _load_jwks(self) -> dict[str, Any]:
-        """Fetches and caches JWKS data from the OIDC metadata."""
-        if self._jwks_data is None:
-            metadata = await self._discover()
-            jwks_uri = metadata["jwks_uri"]
-            self._jwks_data = await fetch_jwks(
-                jwks_uri=jwks_uri,
-                custom_fetch=self.options.custom_fetch
-            )
-        return self._jwks_data
+    async def _discover(self, issuer: Optional[str] = None) -> dict[str, Any]:
+        """
+        Lazy-load OIDC discovery metadata.
+
+        Args:
+            issuer: Optional issuer URL to fetch discovery from (MCD mode).
+                   If provided, extracts domain from issuer URL.
+                   If None, uses configured domain.
+
+        Returns:
+            OIDC discovery metadata dictionary
+        """
+        if issuer:
+            cache_key = issuer  # Already normalized by caller
+            domain = issuer.replace('https://', '').replace('http://', '').rstrip('/')
+        else:
+            domain = self.options.domain
+            cache_key = normalize_domain(f"https://{domain}")
+
+        cached = self._discovery_cache.get(cache_key)
+        if cached:
+            return cached
+
+        metadata, max_age = await fetch_oidc_metadata(
+            domain=domain,
+            custom_fetch=self.options.custom_fetch
+        )
+
+        effective_ttl = self._cache_ttl
+        if max_age is not None and self._cache_ttl is not None:
+            effective_ttl = min(max_age, self._cache_ttl)
+        elif max_age is not None:
+            effective_ttl = max_age
+
+        self._discovery_cache.set(cache_key, metadata, ttl_seconds=effective_ttl)
+        return metadata
+
+    async def _fetch_jwks(self, jwks_uri: str) -> dict[str, Any]:
+        """
+        Fetch JWKS with per-URI caching.
+
+        Args:
+            jwks_uri: The JWKS URI to fetch from
+
+        Returns:
+            JWKS data dictionary
+
+        """
+        cache_key = jwks_uri
+
+        cached = self._jwks_cache.get(cache_key)
+        if cached:
+            return cached
+
+        jwks_data, max_age = await fetch_jwks(
+            jwks_uri=jwks_uri,
+            custom_fetch=self.options.custom_fetch
+        )
+
+        effective_ttl = self._cache_ttl
+        if max_age is not None and self._cache_ttl is not None:
+            effective_ttl = min(max_age, self._cache_ttl)
+        elif max_age is not None:
+            effective_ttl = max_age
+
+        self._jwks_cache.set(cache_key, jwks_data, ttl_seconds=effective_ttl)
+        return jwks_data
 
     def _validate_claims_presence(
         self,

auth0_api_python/cache.py

@@ -0,0 +1,168 @@
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class CacheAdapter(ABC):
+    """
+    Abstract base class for cache implementations.
+
+    Allows custom cache backends (Redis, Memcached, etc.) to be plugged into
+    the ApiClient for caching OIDC discovery metadata and JWKS.
+
+    Example:
+        class RedisCache(CacheAdapter):
+            def __init__(self, redis_client):
+                self.redis = redis_client
+
+            def get(self, key: str) -> Optional[Any]:
+                value = self.redis.get(key)
+                return json.loads(value) if value else None
+
+            def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+                self.redis.set(key, json.dumps(value), ex=ttl_seconds)
+
+            def delete(self, key: str) -> None:
+                self.redis.delete(key)
+
+            def clear(self) -> None:
+                self.redis.flushdb()
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from cache by key.
+
+        Args:
+            key: Cache key to retrieve
+
+        Returns:
+            Cached value if found and not expired, None otherwise
+        """
+        pass
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        """
+        Set value in cache with optional TTL.
+
+        Args:
+            key: Cache key to store
+            value: Value to cache
+            ttl_seconds: Time-to-live in seconds. None means no expiration.
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """
+        Delete value from cache.
+
+        Args:
+            key: Cache key to delete
+        """
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        pass
+
+
+class InMemoryCache(CacheAdapter):
+    """
+    Default in-memory cache implementation with LRU eviction.
+
+    Designed for asyncio (single-threaded).
+    For multi-threaded environments, implement a custom CacheAdapter
+    with appropriate locking.
+
+    Features:
+    - TTL (time-to-live) support per entry using monotonic clock
+    - LRU (Least Recently Used) eviction when max_entries reached
+    - No external dependencies
+
+    Args:
+        max_entries: Maximum number of entries to cache. When exceeded,
+                    least recently used entry is evicted. Default: 100.
+
+    Example:
+        cache = InMemoryCache(max_entries=50)
+        cache.set("key1", {"data": "value"}, ttl_seconds=600)
+        value = cache.get("key1")  # Returns {"data": "value"}
+    """
+
+    def __init__(self, max_entries: int = 100):
+        """
+        Initialize in-memory cache.
+
+        Args:
+            max_entries: Maximum number of cache entries (default: 100)
+        """
+        self._cache: dict[str, tuple[Any, Optional[float]]] = {}
+        self._max_entries = max_entries
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from cache by key.
+
+        Updates access order for LRU tracking.
+
+        Args:
+            key: Cache key to retrieve
+
+        Returns:
+            Cached value if found and not expired, None otherwise
+        """
+        if key not in self._cache:
+            return None
+
+        value, expiry = self._cache[key]
+
+        if expiry is not None and time.monotonic() > expiry:
+            del self._cache[key]
+            return None
+
+        del self._cache[key]
+        self._cache[key] = (value, expiry)
+
+        return value
+
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
+        """
+        Set value in cache with optional TTL.
+
+        If cache is at max capacity, evicts least recently used entry.
+
+        Args:
+            key: Cache key to store
+            value: Value to cache
+            ttl_seconds: Time-to-live in seconds. None means no expiration.
+        """
+        # If key exists, remove first so reinsert goes to end
+        if key in self._cache:
+            del self._cache[key]
+        elif len(self._cache) >= self._max_entries:
+            # Evict LRU: first key in dict is oldest
+            oldest_key = next(iter(self._cache))
+            del self._cache[oldest_key]
+
+        expiry = None
+        if ttl_seconds is not None:
+            expiry = time.monotonic() + ttl_seconds
+
+        self._cache[key] = (value, expiry)
+
+    def delete(self, key: str) -> None:
+        """
+        Delete value from cache.
+
+        Args:
+            key: Cache key to delete
+        """
+        self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        self._cache.clear()

auth0_api_python/config.py

@@ -2,7 +2,10 @@
 Configuration classes and utilities for auth0-api-python.
 """
 
-from typing import Callable, Optional
+from typing import TYPE_CHECKING, Callable, Optional, Union
+
+if TYPE_CHECKING:
+    from .cache import CacheAdapter
 
 
 class ApiClientOptions:
@@ -10,9 +13,16 @@ class ApiClientOptions:
     Configuration for the ApiClient.
 
     Args:
-        domain: The Auth0 domain, e.g., "my-tenant.us.auth0.com".
+        domain: The Auth0 domain for single-domain mode and client flows,
+                e.g., "my-tenant.us.auth0.com". Optional if domains is provided.
+        domains: List of allowed domains or a resolver function for multi-domain mode.
+                 Can be a static list of domain strings or a callable that returns
+                 allowed domains dynamically. Optional if domain is provided.
         audience: The expected 'aud' claim in the token.
         custom_fetch: Optional callable that can replace the default HTTP fetch logic.
+        cache_adapter: Custom cache implementation. If not provided, uses default InMemoryCache.
+        cache_ttl_seconds: Time-to-live for cache entries in seconds (default: 600 = 10 minutes).
+        cache_max_entries: Maximum number of cache entries before LRU eviction (default: 100).
         dpop_enabled: Whether DPoP is enabled (default: True for backward compatibility).
         dpop_required: Whether DPoP is required (default: False, allows both Bearer and DPoP).
         dpop_iat_leeway: Leeway in seconds for DPoP proof iat claim (default: 30).
@@ -23,9 +33,13 @@ class ApiClientOptions:
     """
     def __init__(
             self,
-            domain: str,
-            audience: str,
+            domain: Optional[str] = None,
+            audience: str = "",
+            domains: Optional[Union[list[str], Callable[[dict], list[str]]]] = None,
             custom_fetch: Optional[Callable[..., object]] = None,
+            cache_adapter: Optional["CacheAdapter"] = None,
+            cache_ttl_seconds: int = 600,
+            cache_max_entries: int = 100,
             dpop_enabled: bool = True,
             dpop_required: bool = False,
             dpop_iat_leeway: int = 30,
@@ -35,8 +49,12 @@ class ApiClientOptions:
             timeout: float = 10.0,
     ):
         self.domain = domain
+        self.domains = domains
         self.audience = audience
         self.custom_fetch = custom_fetch
+        self.cache_adapter = cache_adapter
+        self.cache_ttl_seconds = cache_ttl_seconds
+        self.cache_max_entries = cache_max_entries
         self.dpop_enabled = dpop_enabled
         self.dpop_required = dpop_required
         self.dpop_iat_leeway = dpop_iat_leeway

auth0_api_python/errors.py

@@ -140,3 +140,23 @@ class ApiError(BaseAuthError):
 
     def get_error_code(self) -> str:
         return self.code
+
+
+class ConfigurationError(BaseAuthError):
+    """Error raised when SDK configuration is invalid."""
+
+    def get_status_code(self) -> int:
+        return 500
+
+    def get_error_code(self) -> str:
+        return "invalid_configuration"
+
+
+class DomainsResolverError(BaseAuthError):
+    """Error raised when domains resolver function fails."""
+
+    def get_status_code(self) -> int:
+        return 500
+
+    def get_error_code(self) -> str:
+        return "domains_resolver_error"

auth0_api_python/types.py

@@ -0,0 +1,53 @@
+"""
+Type definitions for auth0-api-python SDK
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Optional, TypedDict, Union
+
+
+class DomainsResolverContext(TypedDict, total=False):
+    """
+    Context passed to domains resolver functions.
+
+    Attributes:
+        request_url: The URL the API request was made to (optional)
+        request_headers: Request headers dict (e.g., Host, X-Forwarded-Host) (optional)
+        unverified_iss: The issuer claim from the unverified token
+    """
+    request_url: Optional[str]
+    request_headers: Optional[dict]
+    unverified_iss: str
+
+DomainsResolver = Callable[
+    [DomainsResolverContext], Union[list[str], Awaitable[list[str]]]
+]
+"""
+Type alias for domains resolver function.
+
+A DomainsResolver is a sync or async function that receives a DomainsResolverContext
+and returns a list of allowed domain strings.
+
+Args:
+    context (DomainsResolverContext): Dictionary containing:
+        - 'request_url' (str | None): The URL the API request was made to
+        - 'request_headers' (dict | None): Request headers (e.g., Host, X-Forwarded-Host)
+        - 'unverified_iss' (str): The issuer claim from the unverified token
+
+Returns:
+    list[str]: List of allowed domain strings (e.g., ['tenant.auth0.com'])
+
+Example (sync):
+    from auth0_api_python import DomainsResolverContext
+
+    def my_resolver(context: DomainsResolverContext) -> list[str]:
+        host = (context.get('request_headers') or {}).get('host')
+        if host == 'api.brand.com':
+            return ['brand.custom-domain.com']
+        return ['tenant.auth0.com']
+
+Example (async):
+    async def my_async_resolver(context: DomainsResolverContext) -> list[str]:
+        domains = await db.lookup_domains(context['unverified_iss'])
+        return domains
+"""

auth0_api_python/utils.py

@@ -7,57 +7,147 @@ import base64
 import hashlib
 import json
 import re
+from collections.abc import Mapping
 from typing import Any, Callable, Optional, Union
 
 import httpx
 from ada_url import URL
 
 
+def parse_cache_control_max_age(headers: Mapping[str, str]) -> Optional[int]:
+    """
+    Parse the max-age directive from a Cache-Control HTTP header.
+
+    Args:
+        headers: HTTP response headers (dict-like, supports case-insensitive
+                 access for httpx Headers objects)
+
+    Returns:
+        max-age value in seconds, or None if not present or unparseable
+    """
+    cache_control = headers.get("cache-control") or headers.get("Cache-Control")
+    if not cache_control:
+        return None
+
+    for directive in cache_control.split(","):
+        directive = directive.strip().lower()
+        if directive.startswith("max-age="):
+            try:
+                value = int(directive[8:].strip())
+                return value if value >= 0 else None
+            except ValueError:
+                return None
+
+    return None
+
+
+def normalize_domain(domain: str) -> str:
+    """
+    Normalize a domain string to a standard issuer URL format.
+
+    Args:
+        domain: Domain string in any format (e.g., "tenant.auth0.com",
+                "https://tenant.auth0.com/", "TENANT.AUTH0.COM")
+
+    Returns:
+        Normalized issuer URL (e.g., "https://tenant.auth0.com/")
+
+    """
+    if not isinstance(domain, str) or not domain.strip():
+        raise ValueError("domain must be a non-empty string")
+
+    domain = domain.strip().lower()
+
+    # Reject http:// explicitly
+    if domain.startswith('http://'):
+        raise ValueError("invalid domain URL (https required)")
+
+    # Strip https:// prefix
+    domain = domain.replace('https://', '')
+
+    # Split host from any path/query/fragment
+    host = domain.split('/')[0].split('?')[0].split('#')[0]
+
+    # Reject credentials
+    if '@' in host:
+        raise ValueError("invalid domain URL (credentials are not allowed)")
+
+    # Check for path segments, query, or fragment
+    bare = domain.rstrip('/')
+    if bare != host:
+        raise ValueError(
+            "invalid domain URL (path/query/fragment are not allowed)"
+        )
+
+    return f"https://{host}/"
+
+
 async def fetch_oidc_metadata(
     domain: str,
     custom_fetch: Optional[Callable[..., Any]] = None
-) -> dict[str, Any]:
+) -> tuple[dict[str, Any], Optional[int]]:
     """
     Asynchronously fetch the OIDC config from https://{domain}/.well-known/openid-configuration.
-    Returns a dict with keys like issuer, jwks_uri, authorization_endpoint, etc.
-    If custom_fetch is provided, we call it instead of httpx.
+
+    Returns:
+        Tuple of (metadata_dict, max_age_or_none). max_age is parsed from
+        the Cache-Control response header if present.
     """
     url = f"https://{domain}/.well-known/openid-configuration"
     if custom_fetch:
         response = await custom_fetch(url)
-        return response.json() if hasattr(response, "json") else response
+        if hasattr(response, "json"):
+            data = response.json()
+            max_age = parse_cache_control_max_age(response.headers) if hasattr(response, "headers") else None
+            return data, max_age
+        return response, None
     else:
         async with httpx.AsyncClient() as client:
             resp = await client.get(url)
             resp.raise_for_status()
-            return resp.json()
+            max_age = parse_cache_control_max_age(resp.headers)
+            return resp.json(), max_age
 
 
 async def fetch_jwks(
     jwks_uri: str,
     custom_fetch: Optional[Callable[..., Any]] = None
-) -> dict[str, Any]:
+) -> tuple[dict[str, Any], Optional[int]]:
     """
     Asynchronously fetch the JSON Web Key Set from jwks_uri.
-    Returns the raw JWKS JSON, e.g. {'keys': [...]}
 
-    If custom_fetch is provided, it must be an async callable
-    that fetches data from the jwks_uri.
+    Returns:
+        Tuple of (jwks_dict, max_age_or_none). max_age is parsed from
+        the Cache-Control response header if present.
     """
     if custom_fetch:
         response = await custom_fetch(jwks_uri)
-        return response.json() if hasattr(response, "json") else response
+        if hasattr(response, "json"):
+            data = response.json()
+            max_age = parse_cache_control_max_age(response.headers) if hasattr(response, "headers") else None
+            return data, max_age
+        return response, None
     else:
         async with httpx.AsyncClient() as client:
             resp = await client.get(jwks_uri)
             resp.raise_for_status()
-            return resp.json()
+            max_age = parse_cache_control_max_age(resp.headers)
+            return resp.json(), max_age
 
 
-def get_unverified_header(token: Union[str, bytes]) -> dict:
+def _decode_jwt_segment(token: Union[str, bytes], segment_index: int) -> dict:
     """
-    Parse the first segment (header) of a JWT without verifying signature.
-    Ensures correct Base64 padding before decode to avoid garbage bytes.
+    Decode a specific segment from a JWT without verifying signature.
+
+    Args:
+        token: The JWT token (string or bytes)
+        segment_index: 0 for header, 1 for payload
+
+    Returns:
+        Decoded segment as dictionary
+
+    Raises:
+        ValueError: If token format is invalid
     """
     if isinstance(token, bytes):
         token = token.decode("utf-8")
@@ -66,12 +156,38 @@ def get_unverified_header(token: Union[str, bytes]) -> dict:
     if len(parts) != 3:
         raise ValueError(f"Invalid token format: expected 3 segments, got {len(parts)}")
 
-    header_b64 = parts[0]
-    header_b64 = remove_bytes_prefix(header_b64)
-    header_b64 = fix_base64_padding(header_b64)
+    segment_b64 = parts[segment_index]
+    segment_b64 = remove_bytes_prefix(segment_b64)
+    segment_b64 = fix_base64_padding(segment_b64)
+
+    segment_data = base64.urlsafe_b64decode(segment_b64)
+    return json.loads(segment_data)
 
-    header_data = base64.urlsafe_b64decode(header_b64)
-    return json.loads(header_data)
+
+def get_unverified_header(token: Union[str, bytes]) -> dict:
+    """
+    Parse the JWT header without verifying signature.
+
+    Args:
+        token: The JWT token
+
+    Returns:
+        Decoded header as dictionary
+    """
+    return _decode_jwt_segment(token, 0)
+
+
+def get_unverified_payload(token: Union[str, bytes]) -> dict:
+    """
+    Parse the JWT payload without verifying signature.
+
+    Args:
+        token: The JWT token
+
+    Returns:
+        Decoded payload (claims) as dictionary
+    """
+    return _decode_jwt_segment(token, 1)
 
 
 

{auth0_api_python-1.0.0b6.dist-info → auth0_api_python-1.0.0b8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-api-python
-Version: 1.0.0b6
+Version: 1.0.0b8
 Summary: SDK for verifying access tokens and securing APIs with Auth0, using Authlib.
 License: MIT
 License-File: LICENSE
@@ -15,7 +15,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: ada-url (>=1.27.0,<2.0.0)
+Requires-Dist: ada-url (>=1.27.0,<2.0.0) ; python_version == "3.9"
+Requires-Dist: ada-url (>=1.30.0,<2.0.0) ; python_version >= "3.10"
 Requires-Dist: authlib (>=1.0,<2.0)
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
@@ -40,7 +41,8 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 
 ### **Core Features**
 - **Unified Entry Point**: `verify_request()` - automatically detects and validates Bearer or DPoP schemes
-- **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS
+- **Multi-Custom Domain (MCD)** - Accept tokens from multiple Auth0 domains with static lists or dynamic resolvers
+- **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS with per-issuer caching
 - **JWT Validation** - Complete RS256 signature verification with claim validation
 - **DPoP Proof Verification** - Full RFC 9449 compliance with ES256 signature validation
 - **Flexible Configuration** - Support for both "Allowed" and "Required" DPoP modes
@@ -249,9 +251,6 @@ If the token lacks `my_custom_claim` or fails any standard check (issuer mismatc
 
 ### 6. DPoP Authentication
 
-> [!NOTE]  
-> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.
-
 This library supports **DPoP (Demonstrating Proof-of-Possession)** for enhanced security, allowing clients to prove possession of private keys bound to access tokens.
 
 #### Allowed Mode (Default)
@@ -302,6 +301,50 @@ api_client = ApiClient(ApiClientOptions(
 ))
 ```
 
+### 7. Multi-Custom Domain (MCD) Support
+
+If your Auth0 tenant has multiple custom domains, or you're migrating between domains, the SDK can accept tokens from any of them:
+
+#### Static Domain List
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions
+
+api_client = ApiClient(ApiClientOptions(
+    domains=[
+        "tenant.auth0.com",
+        "auth.example.com",
+        "auth.acme.org"
+    ],
+    audience="https://api.example.com"
+))
+
+# Tokens from any of the three domains are accepted
+claims = await api_client.verify_access_token(access_token)
+```
+
+#### Dynamic Resolver
+
+For runtime domain resolution based on request context:
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions, DomainsResolverContext
+
+def resolve_domains(context: DomainsResolverContext) -> list[str]:
+    # Determine allowed domains based on the request
+    return ["tenant.auth0.com", "auth.example.com"]
+
+api_client = ApiClient(ApiClientOptions(
+    domains=resolve_domains,
+    audience="https://api.example.com"
+))
+```
+
+For hybrid mode (migration scenarios), resolver patterns, error handling, and caching configuration, see the full guides:
+
+- **[Multi-Custom Domain Guide](docs/MultipleCustomDomain.md)** - Configuration modes, resolver patterns, migration, error handling
+- **[Caching Guide](docs/Caching.md)** - Cache tuning, custom adapters (Redis, Memcached)
+
 ## Feedback
 
 ### Contributing

auth0_api_python-1.0.0b8.dist-info/RECORD

@@ -0,0 +1,12 @@
+auth0_api_python/__init__.py,sha256=z8npiH8GBhUexAn_ejh4pnq865dXy7xSaNkQDYJwgGM,725
+auth0_api_python/api_client.py,sha256=pfnyTauurTXQ8_txqE8ZH20UZqXFv9I_EGbn6-9HXgU,48864
+auth0_api_python/cache.py,sha256=MYLssrVx9dYYDNi5JHWHQZgvNrohPtHRKu9n3A76G-I,4689
+auth0_api_python/config.py,sha256=3S0VIO12FCxPPUz15MSMJC5whao3J0u0aSnEivznbZs,3020
+auth0_api_python/errors.py,sha256=5yAwWy7Y9eMtWO-dYRnTfj66ZXCGSzfSqvF3lcPSixI,4513
+auth0_api_python/token_utils.py,sha256=iWCCy15TSjSS6b-2hWpeFY8bDXComkOFI9cINgoGIWs,8026
+auth0_api_python/types.py,sha256=VmOxBmNThn8Q7JVOv6Nloqu6RZ4v8jp5PxJWJFaxtD4,1789
+auth0_api_python/utils.py,sha256=vsdLCzy367xOKlxWE2G8Mu62CZ9wp6fLXl9NSnHPIf8,8285
+auth0_api_python-1.0.0b8.dist-info/METADATA,sha256=oLDtdMsHG6wAOxABXG64ph7D-c_-gc8q_oQxslsgW1o,15104
+auth0_api_python-1.0.0b8.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+auth0_api_python-1.0.0b8.dist-info/licenses/LICENSE,sha256=EEi9tibVAgKdGU1DmXmHjZFOwMfYXDV45mabfEmULkQ,1116
+auth0_api_python-1.0.0b8.dist-info/RECORD,,

{auth0_api_python-1.0.0b6.dist-info → auth0_api_python-1.0.0b8.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
+Generator: poetry-core 2.3.2
 Root-Is-Purelib: true
 Tag: py3-none-any

auth0_api_python-1.0.0b6.dist-info/RECORD

@@ -1,10 +0,0 @@
-auth0_api_python/__init__.py,sha256=mFAanTbu-DXqxV-VHA7awj76CjQ6u4LrKD_b6gBFtcE,407
-auth0_api_python/api_client.py,sha256=Kv6Mm-ZcMY5LTXYI0SPjA9WvAG0LwzcOIbFTnRY48bM,37725
-auth0_api_python/config.py,sha256=VL2VpFz7GFu9Pf31t0Bo7dJ6lpYJEwwlwm-BZ6T2Ygg,1889
-auth0_api_python/errors.py,sha256=eSwwl1Fb0E5C78oFSFj70cYep-wGe6ddKVPJZDNn1gQ,4035
-auth0_api_python/token_utils.py,sha256=iWCCy15TSjSS6b-2hWpeFY8bDXComkOFI9cINgoGIWs,8026
-auth0_api_python/utils.py,sha256=bIMtKe3WOtut0YpaFvPwMs_OO0Q9DWeDVoExKmg-txg,4976
-auth0_api_python-1.0.0b6.dist-info/METADATA,sha256=mO9dNrpNiiT3salWMU5NzwZ7ifIZcFL9U78QtHMSges,13724
-auth0_api_python-1.0.0b6.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-auth0_api_python-1.0.0b6.dist-info/licenses/LICENSE,sha256=EEi9tibVAgKdGU1DmXmHjZFOwMfYXDV45mabfEmULkQ,1116
-auth0_api_python-1.0.0b6.dist-info/RECORD,,