auth0-server-python 1.0.0b9__tar.gz → 1.0.0b11__tar.gz

{auth0_server_python-1.0.0b9 → auth0_server_python-1.0.0b11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b9
+Version: 1.0.0b11
 Summary: Auth0 server-side Python SDK
 License: MIT
 License-File: LICENSE
@@ -129,6 +129,10 @@ async def callback(request: Request):
     return RedirectResponse(url="/")
 ```
 
+#### Organizations
+
+The SDK supports [Auth0 Organizations](https://auth0.com/docs/organizations) with first-class `organization` and `invitation` parameters on `ServerClient` and `StartInteractiveLoginOptions`. Token claim validation is enforced automatically at callback. For setup, invitation flows, error handling, and reading org data from the session, see [examples/InteractiveLogin.md](examples/InteractiveLogin.md#8-organizations).
+
 ### 4. Login with Custom Token Exchange
 
 If you're migrating from a legacy authentication system or integrating with a custom identity provider, you can exchange external tokens for Auth0 tokens using the OAuth 2.0 Token Exchange specification (RFC 8693):

{auth0_server_python-1.0.0b9 → auth0_server_python-1.0.0b11}/README.md

@@ -104,6 +104,10 @@ async def callback(request: Request):
     return RedirectResponse(url="/")
 ```
 
+#### Organizations
+
+The SDK supports [Auth0 Organizations](https://auth0.com/docs/organizations) with first-class `organization` and `invitation` parameters on `ServerClient` and `StartInteractiveLoginOptions`. Token claim validation is enforced automatically at callback. For setup, invitation flows, error handling, and reading org data from the session, see [examples/InteractiveLogin.md](examples/InteractiveLogin.md#8-organizations).
+
 ### 4. Login with Custom Token Exchange
 
 If you're migrating from a legacy authentication system or integrating with a custom identity provider, you can exchange external tokens for Auth0 tokens using the OAuth 2.0 Token Exchange specification (RFC 8693):

{auth0_server_python-1.0.0b9 → auth0_server_python-1.0.0b11}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-server-python"
-version = "1.0.0b9"
+version = "1.0.0b11"
 description = "Auth0 server-side Python SDK"
 readme = "README.md"
 authors = ["Auth0 <support@okta.com>"]

auth0_server_python-1.0.0b11/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.0b11/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)}"
+            )

{auth0_server_python-1.0.0b9 → auth0_server_python-1.0.0b11}/src/auth0_server_python/auth_server/my_account_client.py

@@ -25,14 +25,21 @@ class MyAccountClient:
     Client for interacting with the Auth0 MyAccount API.
     """
 
-    def __init__(self, domain: str):
+    def __init__(self, domain: str, headers: Optional[dict[str, str]] = None):
         """
         Initialize the MyAccount API client.
 
         Args:
             domain: Auth0 domain (e.g., '<tenant>.<locality>.auth0.com')
+            headers: Optional default headers to include on every request
         """
         self._domain = domain
+        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)
 
     @property
     def audience(self):
@@ -64,7 +71,7 @@ class MyAccountClient:
             ApiError: If the request fails due to network or other issues
         """
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 response = await client.post(
                     url=f"{self.audience}v1/connected-accounts/connect",
                     json=request.model_dump(exclude_none=True),
@@ -114,7 +121,7 @@ class MyAccountClient:
             ApiError: If the request fails due to network or other issues
         """
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 response = await client.post(
                     url=f"{self.audience}v1/connected-accounts/complete",
                     json=request.model_dump(exclude_none=True),
@@ -176,7 +183,7 @@ class MyAccountClient:
             raise InvalidArgumentError("take", "The 'take' parameter must be a positive integer.")
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 params = {}
                 if connection:
                     params["connection"] = connection
@@ -243,7 +250,7 @@ class MyAccountClient:
             raise MissingRequiredArgumentError("connected_account_id")
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 response = await client.delete(
                     url=f"{self.audience}v1/connected-accounts/accounts/{connected_account_id}",
                     auth=BearerAuth(access_token)
@@ -298,7 +305,7 @@ class MyAccountClient:
             raise InvalidArgumentError("take", "The 'take' parameter must be a positive integer.")
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 params = {}
                 if from_param:
                     params["from"] = from_param