auth0-api-python 1.0.0b7__py3-none-any.whl → 1.0.0b9__py3-none-any.whl

auth0_api_python/__init__.py

@@ -5,13 +5,34 @@ A lightweight Python SDK for verifying Auth0-issued access tokens
 in server-side APIs, using Authlib for OIDC discovery and JWKS fetching.
 """
 
+from .act import get_current_actor, get_delegation_chain
 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,
+    OnBehalfOfTokenResult,
+)
 
 __all__ = [
     "ApiClient",
     "ApiClientOptions",
     "ApiError",
-    "GetTokenByExchangeProfileError"
+    "CacheAdapter",
+    "ConfigurationError",
+    "DomainsResolver",
+    "DomainsResolverContext",
+    "DomainsResolverError",
+    "GetTokenByExchangeProfileError",
+    "get_current_actor",
+    "get_delegation_chain",
+    "InMemoryCache",
+    "OnBehalfOfTokenResult",
 ]

auth0_api_python/act.py

@@ -0,0 +1,64 @@
+"""
+Helpers for working with the `act` claim on verified access token claims.
+"""
+
+from collections.abc import Mapping
+from typing import Any, Optional
+
+from .errors import VerifyAccessTokenError
+
+INVALID_ACT_CLAIM_MESSAGE = "Invalid act claim"
+
+
+def get_current_actor(claims: Mapping[str, Any]) -> Optional[str]:
+    """
+    Return the current actor from the outermost `act.sub`, if present.
+
+    Only the outermost `act.sub` should be used for authorization decisions.
+    Nested `act` values represent prior actors and are informational.
+    """
+    if not isinstance(claims, Mapping):
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    act_claim = claims.get("act")
+    if act_claim is None:
+        return None
+
+    if not isinstance(act_claim, Mapping):
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    sub = act_claim.get("sub")
+    if not isinstance(sub, str) or not sub.strip():
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    return sub
+
+
+def get_delegation_chain(claims: Mapping[str, Any]) -> list[str]:
+    """
+    Return the delegation chain from newest actor to oldest actor.
+
+    The first entry is the current actor (outermost `act.sub`). Later entries are
+    prior actors from nested `act` values and are typically most useful for audit
+    and attribution.
+    """
+    if not isinstance(claims, Mapping):
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    current = claims.get("act")
+    if current is None:
+        return []
+
+    chain: list[str] = []
+    while current is not None:
+        if not isinstance(current, Mapping):
+            raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+        sub = current.get("sub")
+        if not isinstance(sub, str) or not sub.strip():
+            raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+        chain.append(sub)
+        current = current.get("act")
+
+    return chain

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,
@@ -17,17 +21,21 @@ from .errors import (
     MissingRequiredArgumentError,
     VerifyAccessTokenError,
 )
+from .types import OnBehalfOfTokenResult
 from .utils import (
     calculate_jwk_thumbprint,
     fetch_jwks,
     fetch_oidc_metadata,
     get_unverified_header,
+    get_unverified_payload,
+    normalize_domain,
     normalize_url_for_htu,
     sha256_base64url,
 )
 
 # Token Exchange constants
 TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"  # noqa: S105
+OBO_ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token"  # noqa: S105
 MAX_ARRAY_VALUES_PER_KEY = 20  # DoS protection for extra parameter arrays
 
 # OAuth parameter denylist - parameters that cannot be overridden via extras
@@ -48,14 +56,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 +122,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,10 +231,10 @@ 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
+            The decoded access token claims, including `act` when present.
 
         Raises:
             MissingRequiredArgumentError: If required args are missing
@@ -171,7 +313,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 +365,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 +395,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 +407,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.
+            The decoded token claims if valid, including `act` when present.
 
         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 +521,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 +533,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")
@@ -555,7 +796,7 @@ class ApiClient:
             Dictionary containing:
             - access_token (str): The Auth0 access token
             - expires_in (int): Token lifetime in seconds
-            - expires_at (int): Unix timestamp when token expires
+            - expires_at (int): Absolute expiration time as a Unix timestamp in seconds, calculated by the SDK from expires_in
             - id_token (str, optional): OpenID Connect ID token
             - refresh_token (str, optional): Refresh token
             - scope (str, optional): Granted scopes
@@ -723,6 +964,64 @@ class ApiClient:
                 exc
             )
 
+    async def get_token_on_behalf_of(
+        self,
+        access_token: str,
+        audience: str,
+        scope: Optional[str] = None,
+    ) -> OnBehalfOfTokenResult:
+        """
+        Exchange an Auth0 access token for another Auth0 access token targeting a downstream API
+        while acting on behalf of the same end user (OBO).
+
+        This is a convenience wrapper around get_token_by_exchange_profile() that fixes the
+        RFC 8693 token types for Auth0 access-token-to-access-token exchange.
+
+        Args:
+            access_token: The Auth0 access token to exchange
+            audience: Target API identifier for the exchanged access token
+            scope: Optional space-separated OAuth 2.0 scopes to request
+
+        Returns:
+            Dictionary containing:
+            - access_token (str): The exchanged Auth0 access token
+            - expires_in (int): Token lifetime in seconds
+            - expires_at (int): Absolute expiration time as a Unix timestamp in seconds, calculated by the SDK from expires_in
+            - scope (str, optional): Granted scopes
+            - token_type (str, optional): Token type (typically "Bearer")
+            - issued_token_type (str, optional): RFC 8693 issued token type identifier
+
+        Raises:
+            MissingRequiredArgumentError: If required parameters are missing
+            GetTokenByExchangeProfileError: If client credentials are not configured or validation fails
+            ApiError: If the token endpoint returns an error
+        """
+        if not audience:
+            raise MissingRequiredArgumentError("audience")
+
+        result = await self.get_token_by_exchange_profile(
+            subject_token=access_token,
+            subject_token_type=OBO_ACCESS_TOKEN_TYPE,
+            audience=audience,
+            scope=scope,
+            requested_token_type=OBO_ACCESS_TOKEN_TYPE,
+        )
+
+        obo_result: OnBehalfOfTokenResult = {
+            "access_token": result["access_token"],
+            "expires_in": result["expires_in"],
+            "expires_at": result["expires_at"],
+        }
+
+        if "scope" in result:
+            obo_result["scope"] = result["scope"]
+        if "token_type" in result:
+            obo_result["token_type"] = result["token_type"]
+        if "issued_token_type" in result:
+            obo_result["issued_token_type"] = result["issued_token_type"]
+
+        return obo_result
+
     # ===== Private Methods =====
 
     def _apply_extra(
@@ -767,25 +1066,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,