auth0-server-python 1.0.0b8__tar.gz → 1.0.0b10__tar.gz

{auth0_server_python-1.0.0b8 → auth0_server_python-1.0.0b10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b8
+Version: 1.0.0b10
 Summary: Auth0 server-side Python SDK
 License: MIT
 License-File: LICENSE
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: authlib (>=1.2,<2.0)
 Requires-Dist: cryptography (>=43.0.1)
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: jwcrypto (>=1.5.6,<2.0.0)
+Requires-Dist: jwcrypto (>=1.5.7,<2.0.0)
 Requires-Dist: pydantic (>=2.10.6,<3.0.0)
 Requires-Dist: pyjwt (>=2.8.0)
 Description-Content-Type: text/markdown
@@ -170,6 +170,34 @@ print(response.access_token)
 
 For more details and examples, see [examples/CustomTokenExchange.md](examples/CustomTokenExchange.md).
 
+### 5. Multiple Custom Domains (MCD)
+
+For applications that use multiple custom domains on the same Auth0 tenant, pass a domain resolver function instead of a static domain string:
+
+```python
+from auth0_server_python.auth_server.server_client import ServerClient
+from auth0_server_python.auth_types import DomainResolverContext
+
+async def domain_resolver(context: DomainResolverContext) -> str:
+    host = context.request_headers.get('host', '').split(':')[0]
+    domain_map = {
+        "acme.yourapp.com": "acme.auth0.com",
+        "globex.yourapp.com": "globex.auth0.com",
+    }
+    return domain_map.get(host, "default.auth0.com")
+
+auth0 = ServerClient(
+    domain=domain_resolver,  # Callable enables MCD mode
+    client_id='<AUTH0_CLIENT_ID>',
+    client_secret='<AUTH0_CLIENT_SECRET>',
+    secret='<AUTH0_SECRET>',
+)
+```
+
+The SDK handles per-domain OIDC discovery, JWKS fetching, issuer validation, and session isolation automatically. Static string domains continue to work unchanged.
+
+For more details and examples, see [examples/MultipleCustomDomains.md](examples/MultipleCustomDomains.md).
+
 ## Feedback
 
 ### Contributing

{auth0_server_python-1.0.0b8 → auth0_server_python-1.0.0b10}/README.md

@@ -145,6 +145,34 @@ print(response.access_token)
 
 For more details and examples, see [examples/CustomTokenExchange.md](examples/CustomTokenExchange.md).
 
+### 5. Multiple Custom Domains (MCD)
+
+For applications that use multiple custom domains on the same Auth0 tenant, pass a domain resolver function instead of a static domain string:
+
+```python
+from auth0_server_python.auth_server.server_client import ServerClient
+from auth0_server_python.auth_types import DomainResolverContext
+
+async def domain_resolver(context: DomainResolverContext) -> str:
+    host = context.request_headers.get('host', '').split(':')[0]
+    domain_map = {
+        "acme.yourapp.com": "acme.auth0.com",
+        "globex.yourapp.com": "globex.auth0.com",
+    }
+    return domain_map.get(host, "default.auth0.com")
+
+auth0 = ServerClient(
+    domain=domain_resolver,  # Callable enables MCD mode
+    client_id='<AUTH0_CLIENT_ID>',
+    client_secret='<AUTH0_CLIENT_SECRET>',
+    secret='<AUTH0_SECRET>',
+)
+```
+
+The SDK handles per-domain OIDC discovery, JWKS fetching, issuer validation, and session isolation automatically. Static string domains continue to work unchanged.
+
+For more details and examples, see [examples/MultipleCustomDomains.md](examples/MultipleCustomDomains.md).
+
 ## Feedback
 
 ### Contributing

{auth0_server_python-1.0.0b8 → auth0_server_python-1.0.0b10}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-server-python"
-version = "1.0.0.b8"
+version = "1.0.0b10"
 description = "Auth0 server-side Python SDK"
 readme = "README.md"
 authors = ["Auth0 <support@okta.com>"]
@@ -17,7 +17,7 @@ pyjwt = ">=2.8.0"
 authlib = "^1.2"
 httpx = "^0.28.1"
 pydantic = "^2.10.6"
-jwcrypto = "^1.5.6"
+jwcrypto = "^1.5.7"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.2"
@@ -25,7 +25,7 @@ pytest-cov = "^4.0"
 pytest-asyncio = ">=0.20.3,<0.24.0"
 pytest-mock = "^3.14.0"
 twine = "^6.1.0"
-ruff = "^0.1.0"
+ruff = ">=0.1"
 
 [tool.pytest.ini_options]
 addopts = "--cov=auth0_server_python --cov-report=term-missing:skip-covered --cov-report=xml"

auth0_server_python-1.0.0b10/src/auth0_server_python/auth_server/__init__.py

@@ -0,0 +1,5 @@
+from .mfa_client import MfaClient
+from .my_account_client import MyAccountClient
+from .server_client import ServerClient
+
+__all__ = ["ServerClient", "MyAccountClient", "MfaClient"]

auth0_server_python-1.0.0b10/src/auth0_server_python/auth_server/mfa_client.py

@@ -0,0 +1,528 @@
+"""
+MFA Client for auth0-server-python SDK.
+Handles Multi-Factor Authentication operations against the Auth0 MFA API.
+"""
+
+import time
+from typing import Any, Callable, Optional, Union
+
+import httpx
+
+from auth0_server_python.auth_schemes.bearer_auth import BearerAuth
+from auth0_server_python.auth_types import (
+    AuthenticatorResponse,
+    ChallengeResponse,
+    EnrollmentResponse,
+    MfaRequirements,
+    MfaTokenContext,
+    MfaVerifyResponse,
+    OobEnrollmentResponse,
+    OtpEnrollmentResponse,
+    StateData,
+    TokenSet,
+)
+from auth0_server_python.encryption.encrypt import decrypt, encrypt
+from auth0_server_python.error import (
+    DomainResolverError,
+    MfaChallengeError,
+    MfaEnrollmentError,
+    MfaListAuthenticatorsError,
+    MfaRequiredError,
+    MfaTokenExpiredError,
+    MfaTokenInvalidError,
+    MfaVerifyError,
+)
+from auth0_server_python.utils.helpers import (
+    build_domain_resolver_context,
+    validate_resolved_domain_value,
+)
+
+DEFAULT_MFA_TOKEN_TTL = 300  # 5 minutes
+
+
+class MfaClient:
+    """
+    Client for Auth0 MFA API operations.
+
+    Provides methods for listing authenticators, enrolling new authenticators,
+    deleting authenticators, challenging authenticators, and verifying MFA codes.
+
+    All API operations require a raw mfa_token. If the token was encrypted
+    (e.g. from MfaRequiredError raised by get_access_token()), use
+    decrypt_mfa_token() first to obtain the raw token.
+    """
+
+    def __init__(
+        self,
+        domain: Union[str, Callable, None],
+        client_id: str,
+        client_secret: str,
+        secret: str,
+        state_store=None,
+        state_identifier: str = "_a0_session",
+        headers: Optional[dict[str, str]] = None
+    ):
+        if callable(domain):
+            self._domain = None
+            self._domain_resolver = domain
+        else:
+            self._domain = domain
+            self._domain_resolver = None
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._secret = secret
+        self._state_store = state_store
+        self._state_identifier = state_identifier
+        self._headers = headers or {}
+
+    def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
+        """Return an httpx.AsyncClient with default headers injected."""
+        headers = {**kwargs.pop("headers", {}), **self._headers}
+        return httpx.AsyncClient(headers=headers, **kwargs)
+
+    async def _resolve_base_url(
+        self,
+        store_options: Optional[dict[str, Any]] = None
+    ) -> str:
+        """Resolve domain and return base URL for API calls."""
+        if self._domain_resolver:
+            context = build_domain_resolver_context(store_options)
+            try:
+                resolved = await self._domain_resolver(context)
+                domain = validate_resolved_domain_value(resolved)
+            except DomainResolverError:
+                raise
+            except Exception as e:
+                raise DomainResolverError(
+                    f"Domain resolver function raised an exception: {str(e)}",
+                    original_error=e
+                )
+        else:
+            domain = self._domain
+        return f"https://{domain}"
+
+    # ============================================================================
+    # MFA TOKEN ENCRYPTION / DECRYPTION
+    # ============================================================================
+
+    def _encrypt_mfa_token(
+        self,
+        raw_mfa_token: str,
+        audience: str,
+        scope: str,
+        mfa_requirements: Optional[MfaRequirements] = None,
+    ) -> str:
+        """Encrypt an MFA token with context for secure client-side storage."""
+        context = MfaTokenContext(
+            mfa_token=raw_mfa_token,
+            audience=audience,
+            scope=scope,
+            mfa_requirements=mfa_requirements,
+            created_at=int(time.time())
+        )
+        return encrypt(context.model_dump(), self._secret, "mfa_token")
+
+    def decrypt_mfa_token(self, encrypted_token: str) -> MfaTokenContext:
+        """Decrypt an MFA token and validate TTL."""
+        try:
+            payload = decrypt(encrypted_token, self._secret, "mfa_token")
+            context = MfaTokenContext(**payload)
+        except Exception:
+            raise MfaTokenInvalidError()
+
+        # Check TTL
+        elapsed = int(time.time()) - context.created_at
+        if elapsed > DEFAULT_MFA_TOKEN_TTL:
+            raise MfaTokenExpiredError()
+
+        return context
+
+    # ============================================================================
+    # MFA API OPERATIONS
+    # ============================================================================
+
+    async def list_authenticators(
+        self,
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
+    ) -> list[AuthenticatorResponse]:
+        """
+        Lists all MFA authenticators enrolled by the user.
+
+        Args:
+            options: Dict containing 'mfa_token' (raw, decrypted).
+            store_options: Optional options passed to the State Store (e.g. request/response).
+
+        Returns:
+            List of enrolled authenticators.
+
+        Raises:
+            MfaListAuthenticatorsError: When the request fails.
+        """
+        mfa_token = options["mfa_token"]
+        base_url = await self._resolve_base_url(store_options)
+        url = f"{base_url}/mfa/authenticators"
+
+        try:
+            async with self._get_http_client() as client:
+                response = await client.get(
+                    url,
+                    auth=BearerAuth(mfa_token)
+                )
+
+                if response.status_code != 200:
+                    error_data = response.json()
+                    raise MfaListAuthenticatorsError(
+                        error_data.get("error_description", "Failed to list authenticators"),
+                        error_data
+                    )
+
+                api_response = response.json()
+                return [AuthenticatorResponse(**auth) for auth in api_response]
+
+        except MfaListAuthenticatorsError:
+            raise
+        except Exception as e:
+            raise MfaListAuthenticatorsError(
+                f"Unexpected error listing authenticators: {str(e)}"
+            )
+
+    async def enroll_authenticator(
+        self,
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
+    ) -> EnrollmentResponse:
+        """
+        Enrolls a new MFA authenticator for the user.
+
+        Args:
+            options: Dict containing enrollment parameters.
+                Required: 'mfa_token', 'factor_type' (otp, sms, voice, email, auth0).
+                Optional: 'phone_number', 'email'.
+            store_options: Optional options passed to the State Store (e.g. request/response).
+
+        Returns:
+            OtpEnrollmentResponse or OobEnrollmentResponse.
+
+        Raises:
+            MfaEnrollmentError: When enrollment fails.
+        """
+        mfa_token = options["mfa_token"]
+        factor_type = options["factor_type"]
+        base_url = await self._resolve_base_url(store_options)
+        url = f"{base_url}/mfa/associate"
+
+        # Map factor_type to Auth0 API parameters
+        if factor_type == "otp":
+            authenticator_type = "otp"
+            oob_channels = None
+        elif factor_type in ["sms", "voice", "email", "auth0"]:
+            authenticator_type = "oob"
+            oob_channels = factor_type
+        else:
+            raise MfaEnrollmentError(
+                f"Unsupported factor_type: {factor_type}. Supported types: otp, sms, voice, email, auth0"
+            )
+
+        # Build API request body
+        body: dict[str, Any] = {
+            "authenticator_types": [authenticator_type]
+        }
+
+        if oob_channels:
+            body["oob_channels"] = [oob_channels]
+
+        if "phone_number" in options and options["phone_number"]:
+            body["phone_number"] = options["phone_number"]
+
+        if "email" in options and options["email"]:
+            body["email"] = options["email"]
+
+        try:
+            async with self._get_http_client() as client:
+                response = await client.post(
+                    url,
+                    json=body,
+                    auth=BearerAuth(mfa_token),
+                    headers={"Content-Type": "application/json"}
+                )
+
+                if response.status_code != 200:
+                    error_data = response.json()
+                    raise MfaEnrollmentError(
+                        error_data.get("error_description", "Failed to enroll authenticator"),
+                        error_data
+                    )
+
+                api_response = response.json()
+                authenticator_type = api_response.get("authenticator_type")
+
+                if authenticator_type == "otp":
+                    return OtpEnrollmentResponse(**api_response)
+                elif authenticator_type == "oob":
+                    return OobEnrollmentResponse(**api_response)
+                else:
+                    raise MfaEnrollmentError(
+                        f"Unexpected authenticator type: {authenticator_type}"
+                    )
+
+        except MfaEnrollmentError:
+            raise
+        except Exception as e:
+            raise MfaEnrollmentError(
+                f"Unexpected error enrolling authenticator: {str(e)}"
+            )
+
+    async def challenge_authenticator(
+        self,
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
+    ) -> ChallengeResponse:
+        """
+        Initiates an MFA challenge for user verification.
+
+        Args:
+            options: Dict containing 'mfa_token', 'factor_type' (otp, sms, voice, email, auth0),
+                and optionally 'authenticator_id'.
+            store_options: Optional options passed to the State Store (e.g. request/response).
+
+        Returns:
+            ChallengeResponse with challenge details.
+
+        Raises:
+            MfaChallengeError: When the challenge fails.
+        """
+        mfa_token = options["mfa_token"]
+        factor_type = options["factor_type"]
+        base_url = await self._resolve_base_url(store_options)
+        url = f"{base_url}/mfa/challenge"
+
+        # Map factor_type to Auth0 API challenge_type
+        if factor_type == "otp":
+            challenge_type = "otp"
+        elif factor_type in ["sms", "voice", "email", "auth0"]:
+            challenge_type = "oob"
+        else:
+            raise MfaChallengeError(
+                f"Unsupported factor_type: {factor_type}. Supported types: otp, sms, voice, email, auth0"
+            )
+
+        body: dict[str, Any] = {
+            "mfa_token": mfa_token,
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+            "challenge_type": challenge_type
+        }
+
+        if "authenticator_id" in options and options["authenticator_id"]:
+            body["authenticator_id"] = options["authenticator_id"]
+
+        try:
+            async with self._get_http_client() as client:
+                response = await client.post(
+                    url,
+                    json=body,
+                    headers={"Content-Type": "application/json"}
+                )
+
+                if response.status_code != 200:
+                    error_data = response.json()
+                    raise MfaChallengeError(
+                        error_data.get("error_description", "Failed to challenge authenticator"),
+                        error_data
+                    )
+
+                api_response = response.json()
+                return ChallengeResponse(**api_response)
+
+        except MfaChallengeError:
+            raise
+        except Exception as e:
+            raise MfaChallengeError(
+                f"Unexpected error challenging authenticator: {str(e)}"
+            )
+
+    async def verify(
+        self,
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
+    ) -> MfaVerifyResponse:
+        """
+        Verifies an MFA code and completes authentication.
+
+        Supports OTP, OOB (with binding code), and recovery code verification.
+
+        If Auth0 returns 'mfa_required' again (chained MFA), raises MfaRequiredError
+        with a raw mfa_token. The framework SDK (e.g. auth0-fastapi) is responsible
+        for encrypting the token before returning it to the client.
+
+        Args:
+            options: Dict containing 'mfa_token' and one of:
+                - 'otp': OTP code
+                - 'oob_code' + 'binding_code': OOB verification
+                - 'recovery_code': Recovery code
+                - 'persist': bool (optional, default=False) - Persist tokens to state store
+                - 'audience': str (optional, required if persist=True) - Audience for token_set
+                - 'scope': str (optional) - Scope for token_set
+            store_options: Optional options passed to the State Store (e.g. request/response).
+
+        Returns:
+            MfaVerifyResponse with access_token, token_type, etc.
+
+        Raises:
+            MfaVerifyError: When verification fails.
+            MfaRequiredError: When chained MFA is required.
+        """
+        mfa_token = options["mfa_token"]
+
+        # Determine grant type and build body
+        body: dict[str, Any] = {
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+            "mfa_token": mfa_token
+        }
+
+        if "otp" in options:
+            body["grant_type"] = "http://auth0.com/oauth/grant-type/mfa-otp"
+            body["otp"] = options["otp"]
+        elif "oob_code" in options:
+            body["grant_type"] = "http://auth0.com/oauth/grant-type/mfa-oob"
+            body["oob_code"] = options["oob_code"]
+            if options.get("binding_code"):
+                body["binding_code"] = options["binding_code"]
+        elif "recovery_code" in options:
+            body["grant_type"] = "http://auth0.com/oauth/grant-type/mfa-recovery-code"
+            body["recovery_code"] = options["recovery_code"]
+        else:
+            raise MfaVerifyError(
+                "No verification credential provided (otp, oob_code, or recovery_code)"
+            )
+
+        try:
+            base_url = await self._resolve_base_url(store_options)
+            token_endpoint = f"{base_url}/oauth/token"
+
+            async with self._get_http_client() as client:
+                response = await client.post(
+                    token_endpoint,
+                    data=body,
+                    headers={"Content-Type": "application/x-www-form-urlencoded"}
+                )
+
+                if response.status_code != 200:
+                    error_data = response.json()
+
+                    # Handle chained MFA — token is raw; encryption is the
+                    # framework SDK's responsibility (see ServerClient.get_access_token).
+                    if error_data.get("error") == "mfa_required":
+                        new_mfa_token = error_data.get("mfa_token")
+                        mfa_requirements_data = error_data.get("mfa_requirements")
+                        mfa_requirements = None
+                        if mfa_requirements_data:
+                            mfa_requirements = MfaRequirements(**mfa_requirements_data)
+
+                        raise MfaRequiredError(
+                            error_data.get("error_description", "Additional MFA factor required"),
+                            mfa_token=new_mfa_token,
+                            mfa_requirements=mfa_requirements
+                        )
+
+                    raise MfaVerifyError(
+                        error_data.get("error_description", "MFA verification failed"),
+                        error_data
+                    )
+
+                token_response = response.json()
+                verify_response = MfaVerifyResponse(**token_response)
+
+                # Persist tokens to state store if requested
+                if options.get("persist") and self._state_store:
+                    await self._persist_mfa_tokens(
+                        verify_response=verify_response,
+                        options=options,
+                        store_options=store_options
+                    )
+
+                return verify_response
+
+        except (MfaVerifyError, MfaRequiredError):
+            raise
+        except Exception as e:
+            raise MfaVerifyError(
+                f"Unexpected error during MFA verification: {str(e)}"
+            )
+
+    async def _persist_mfa_tokens(
+        self,
+        verify_response: MfaVerifyResponse,
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
+    ) -> None:
+        """
+        Persist MFA verification tokens to the state store.
+
+        Updates the session with the new access_token and id_token from MFA verification.
+
+        Args:
+            verify_response: The response from verify() containing tokens
+            options: Dict containing:
+                - 'audience': str - Audience for token_set
+                - 'scope': str (optional) - Scope for token_set
+            store_options: Optional options passed to the State Store (e.g. request/response).
+        """
+        audience = options.get("audience")
+        scope = options.get("scope")
+
+        if not audience:
+            raise MfaVerifyError(
+                "audience is required when persist=True"
+            )
+
+        try:
+            # Get existing state
+            state_data = await self._state_store.get(
+                self._state_identifier,
+                store_options
+            )
+
+            if not state_data:
+                raise MfaVerifyError(
+                    "No existing session found to update with MFA tokens"
+                )
+
+            # Parse state data
+            existing_state = StateData(**state_data) if isinstance(state_data, dict) else state_data
+
+            # Update id_token if present
+            if verify_response.id_token:
+                existing_state.id_token = verify_response.id_token
+
+            # Create token_set for the access_token
+            expires_at = int(time.time()) + verify_response.expires_in
+
+            new_token_set = TokenSet(
+                audience=audience,
+                access_token=verify_response.access_token,
+                scope=scope,
+                expires_at=expires_at
+            )
+
+            # Add to token_sets, replacing any existing token_set for this audience
+            existing_state.token_sets = [
+                ts for ts in existing_state.token_sets if ts.audience != audience
+            ]
+            existing_state.token_sets.append(new_token_set)
+
+            # Persist updated state
+            await self._state_store.set(
+                self._state_identifier,
+                existing_state.model_dump(),
+                options=store_options
+            )
+
+        except MfaVerifyError:
+            raise
+        except Exception as e:
+            raise MfaVerifyError(
+                f"Failed to persist MFA tokens to state store: {str(e)}"
+            )