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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b11
+Version: 1.0.0b13
 Summary: Auth0 server-side Python SDK
 License: MIT
 License-File: LICENSE
@@ -202,6 +202,24 @@ The SDK handles per-domain OIDC discovery, JWKS fetching, issuer validation, and
 
 For more details and examples, see [examples/MultipleCustomDomains.md](examples/MultipleCustomDomains.md).
 
+### 6. Session Expiry from the Upstream IdP
+
+For enterprise connections, the upstream identity provider can cap how long a user's session lives. When the connection is configured to honor it, Auth0 includes a `session_expiry` claim in the ID token, and the SDK enforces this ceiling on every session read. Once it is reached, `get_user()` and `get_session()` return `None`, and `get_access_token()` raises an `AccessTokenError` with code `session_expired`. If the asserted ceiling is already in the past at login, `complete_interactive_login()` raises a `SessionExpiredError` instead of persisting an already-expired session.
+
+For more details and examples, see [examples/RetrievingData.md](examples/RetrievingData.md#session-expiry-from-the-upstream-idp).
+
+### 7. Passkey Authentication
+
+Sign users up or in with [WebAuthn](https://www.w3.org/TR/webauthn-2/) passkeys (Touch ID, Face ID, Windows Hello, or a security key) instead of a password, via [Auth0 passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys). The ceremony is two steps — request a challenge, sign it in the browser, then complete sign-in — and establishes a server-side session like every other login path. For the signup and login flows, organizations, step-up MFA, and error handling, see [examples/Passkeys.md](examples/Passkeys.md).
+
+### 8. My Account API — Authentication Methods
+
+Let a logged-in user manage their own enrolled authentication methods — enroll a new passkey (or other factor), list, rename, and delete — via the [My Account API](https://auth0.com/docs/manage-users/my-account-api). For obtaining a scoped token, the enroll/verify ceremony, listing, updating, deleting, and error handling, see [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md).
+
+### 9. DPoP — Sender-Constrained Tokens (Passkeys & MyAccount)
+
+Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) so a stolen token alone cannot be replayed. DPoP is supported for Passkey sign-in (`signin_with_passkey`) and the authentication-methods/factors methods on `MyAccountClient`. For key generation and usage, see [examples/Passkeys.md](examples/Passkeys.md#3-dpop-bound-passkey-tokens-optional) and [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md#dpop).
+
 ## Feedback
 
 ### Contributing

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

@@ -177,6 +177,24 @@ The SDK handles per-domain OIDC discovery, JWKS fetching, issuer validation, and
 
 For more details and examples, see [examples/MultipleCustomDomains.md](examples/MultipleCustomDomains.md).
 
+### 6. Session Expiry from the Upstream IdP
+
+For enterprise connections, the upstream identity provider can cap how long a user's session lives. When the connection is configured to honor it, Auth0 includes a `session_expiry` claim in the ID token, and the SDK enforces this ceiling on every session read. Once it is reached, `get_user()` and `get_session()` return `None`, and `get_access_token()` raises an `AccessTokenError` with code `session_expired`. If the asserted ceiling is already in the past at login, `complete_interactive_login()` raises a `SessionExpiredError` instead of persisting an already-expired session.
+
+For more details and examples, see [examples/RetrievingData.md](examples/RetrievingData.md#session-expiry-from-the-upstream-idp).
+
+### 7. Passkey Authentication
+
+Sign users up or in with [WebAuthn](https://www.w3.org/TR/webauthn-2/) passkeys (Touch ID, Face ID, Windows Hello, or a security key) instead of a password, via [Auth0 passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys). The ceremony is two steps — request a challenge, sign it in the browser, then complete sign-in — and establishes a server-side session like every other login path. For the signup and login flows, organizations, step-up MFA, and error handling, see [examples/Passkeys.md](examples/Passkeys.md).
+
+### 8. My Account API — Authentication Methods
+
+Let a logged-in user manage their own enrolled authentication methods — enroll a new passkey (or other factor), list, rename, and delete — via the [My Account API](https://auth0.com/docs/manage-users/my-account-api). For obtaining a scoped token, the enroll/verify ceremony, listing, updating, deleting, and error handling, see [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md).
+
+### 9. DPoP — Sender-Constrained Tokens (Passkeys & MyAccount)
+
+Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) so a stolen token alone cannot be replayed. DPoP is supported for Passkey sign-in (`signin_with_passkey`) and the authentication-methods/factors methods on `MyAccountClient`. For key generation and usage, see [examples/Passkeys.md](examples/Passkeys.md#3-dpop-bound-passkey-tokens-optional) and [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md#dpop).
+
 ## Feedback
 
 ### Contributing

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

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

auth0_server_python-1.0.0b13/src/auth0_server_python/auth_schemes/__init__.py

@@ -0,0 +1,4 @@
+from .bearer_auth import BearerAuth
+from .dpop_auth import DPoPAuth
+
+__all__ = ["BearerAuth", "DPoPAuth"]

auth0_server_python-1.0.0b13/src/auth0_server_python/auth_schemes/dpop_auth.py

@@ -0,0 +1,94 @@
+import base64
+import hashlib
+import time
+import uuid
+from typing import Optional
+
+import httpx
+from jwcrypto import jwk
+from jwcrypto import jwt as jwcrypto_jwt
+
+
+def _base64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _validate_dpop_key(key: "jwk.JWK") -> dict:
+    """Return the public JWK after enforcing the EC P-256 requirement (ES256)."""
+    public_jwk = key.export_public(as_dict=True)
+    if public_jwk.get("kty") != "EC" or public_jwk.get("crv") != "P-256":
+        raise ValueError("DPoP key must be an EC P-256 key")
+    return public_jwk
+
+
+def _build_dpop_proof(
+    key: "jwk.JWK",
+    public_jwk: dict,
+    method: str,
+    url: str,
+    *,
+    ath: Optional[str] = None,
+    nonce: Optional[str] = None,
+) -> str:
+    """Sign a DPoP proof JWT (RFC 9449 §4.2). `ath` binds the proof to an
+    access token and is omitted for token-endpoint proofs."""
+    htu = url.split("?")[0].split("#")[0]
+    header = {"typ": "dpop+jwt", "alg": "ES256", "jwk": public_jwk}
+    payload = {
+        "jti": str(uuid.uuid4()),
+        "htm": method.upper(),
+        "htu": htu,
+        "iat": int(time.time()),
+    }
+    if ath is not None:
+        payload["ath"] = ath
+    if nonce is not None:
+        payload["nonce"] = nonce
+    token = jwcrypto_jwt.JWT(header=header, claims=payload)
+    token.make_signed_token(key)
+    return token.serialize()
+
+
+def make_dpop_proof_for_token_endpoint(
+    key: "jwk.JWK", method: str, url: str, nonce: Optional[str] = None
+) -> str:
+    """
+    Build a DPoP proof JWT for use at the token endpoint (RFC 9449 §4.2).
+    Unlike resource-server proofs, token-endpoint proofs do NOT include `ath`
+    because no access token exists yet at issuance time.
+    """
+    public_jwk = _validate_dpop_key(key)
+    return _build_dpop_proof(key, public_jwk, method, url, nonce=nonce)
+
+
+class DPoPAuth(httpx.Auth):
+    # Buffer the body (sync/async-aware) so the nonce retry can resend it.
+    requires_request_body = True
+
+    def __init__(self, token: str, key: "jwk.JWK") -> None:
+        public_jwk = _validate_dpop_key(key)
+        try:
+            token.encode("ascii")
+        except UnicodeEncodeError:
+            raise ValueError("Access token must contain only ASCII characters")
+        self._token = token
+        self._key = key
+        self._public_jwk = public_jwk
+
+    def auth_flow(self, request: httpx.Request):
+        proof = self._make_proof(request.method, str(request.url))
+        request.headers["Authorization"] = f"DPoP {self._token}"
+        request.headers["DPoP"] = proof
+        response = yield request
+
+        # RFC 9449 §8.2 — server-nonce retry
+        if response.status_code == 401 and response.headers.get("DPoP-Nonce"):
+            nonce = response.headers["DPoP-Nonce"]
+            request.headers["DPoP"] = self._make_proof(
+                request.method, str(request.url), nonce=nonce
+            )
+            yield request
+
+    def _make_proof(self, method: str, url: str, nonce: Optional[str] = None) -> str:
+        ath = _base64url(hashlib.sha256(self._token.encode("ascii")).digest())
+        return _build_dpop_proof(self._key, self._public_jwk, method, url, ath=ath, nonce=nonce)

{auth0_server_python-1.0.0b11 → auth0_server_python-1.0.0b13}/src/auth0_server_python/auth_server/mfa_client.py

@@ -3,12 +3,17 @@ MFA Client for auth0-server-python SDK.
 Handles Multi-Factor Authentication operations against the Auth0 MFA API.
 """
 
+import json
 import time
-from typing import Any, Callable, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union
 
 import httpx
 
 from auth0_server_python.auth_schemes.bearer_auth import BearerAuth
+from auth0_server_python.auth_schemes.dpop_auth import make_dpop_proof_for_token_endpoint
+
+if TYPE_CHECKING:
+    from jwcrypto import jwk
 from auth0_server_python.auth_types import (
     AuthenticatorResponse,
     ChallengeResponse,
@@ -38,6 +43,7 @@ from auth0_server_python.utils.helpers import (
 )
 
 DEFAULT_MFA_TOKEN_TTL = 300  # 5 minutes
+MFA_PENDING_IDENTIFIER = "_a0_mfa_pending"
 
 
 class MfaClient:
@@ -47,9 +53,9 @@ class MfaClient:
     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.
+    All public API methods accept an encrypted mfa_token (as issued by
+    MfaRequiredError) and decrypt it internally. Callers never handle the
+    raw Auth0 mfa_token directly.
     """
 
     def __init__(
@@ -130,13 +136,103 @@ class MfaClient:
         except Exception:
             raise MfaTokenInvalidError()
 
-        # Check TTL
         elapsed = int(time.time()) - context.created_at
         if elapsed > DEFAULT_MFA_TOKEN_TTL:
             raise MfaTokenExpiredError()
 
         return context
 
+    # ============================================================================
+    # MFA STATE
+    # ============================================================================
+
+    @staticmethod
+    def _parse_error_body(response: httpx.Response) -> dict[str, Any]:
+        """
+        Parse an error response body as JSON.
+
+        Falls back to a status-coded stub when the body is not JSON (e.g. a
+        gateway 502/504 HTML page), so the caller always gets a readable dict
+        rather than a JSON-parser exception folded into the message.
+
+        Args:
+            response: The HTTP error response to parse.
+
+        Returns:
+            The parsed JSON object, or a stub dict whose 'error_description'
+            names the HTTP status when the body is not a JSON object.
+        """
+        try:
+            data = response.json()
+        except (json.JSONDecodeError, ValueError):
+            data = None
+        if not isinstance(data, dict):
+            return {
+                "error_description": f"Request failed with status {response.status_code}",
+            }
+        return data
+
+    async def _raise_mfa_required(
+        self,
+        error_data: dict[str, Any],
+        *,
+        audience: str,
+        scope: str,
+        default_description: str,
+        store_pending: bool = False,
+        store_options: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """
+        Encrypt the server-issued mfa_token and raise MfaRequiredError.
+
+        Shared by every site that handles an `mfa_required` response so the
+        encrypt-then-raise behaviour cannot drift between entry points.
+
+        Args:
+            error_data: The parsed `mfa_required` error body from Auth0.
+            audience: Audience to bind into the encrypted token context.
+            scope: Scope to bind into the encrypted token context.
+            default_description: Message used when the response omits
+                'error_description'.
+            store_pending: When True, persist the encrypted token to the state
+                store before raising (the passkey grant does; the refresh-token
+                path relies on its get_access_token caller instead).
+            store_options: Optional options passed to the State Store.
+
+        Returns:
+            None. Returns without raising only when the response carries no
+            mfa_token, so the caller can fall through to its own typed error.
+
+        Raises:
+            MfaRequiredError: When the response carries an mfa_token.
+        """
+        raw_mfa_token = error_data.get("mfa_token")
+        if not raw_mfa_token:
+            return
+        mfa_requirements_data = error_data.get("mfa_requirements")
+        mfa_requirements = (
+            MfaRequirements(**mfa_requirements_data) if mfa_requirements_data else None
+        )
+        encrypted_token = self._encrypt_mfa_token(
+            raw_mfa_token=raw_mfa_token,
+            audience=audience,
+            scope=scope,
+            mfa_requirements=mfa_requirements,
+        )
+        if store_pending and self._state_store:
+            # Persist the in-progress MFA token so challenge and verify can
+            # proceed without the client carrying the token.
+            await self._state_store.set(
+                MFA_PENDING_IDENTIFIER,
+                {"mfa_token": encrypted_token},
+                options=store_options,
+            )
+        raise MfaRequiredError(
+            error_data.get("error_description", default_description),
+            mfa_token=encrypted_token,
+            mfa_requirements=mfa_requirements,
+        )
+
     # ============================================================================
     # MFA API OPERATIONS
     # ============================================================================
@@ -159,7 +255,10 @@ class MfaClient:
         Raises:
             MfaListAuthenticatorsError: When the request fails.
         """
-        mfa_token = options["mfa_token"]
+        mfa_token = options.get("mfa_token")
+        if not mfa_token:
+            raise MfaTokenInvalidError()
+        context = self.decrypt_mfa_token(mfa_token)
         base_url = await self._resolve_base_url(store_options)
         url = f"{base_url}/mfa/authenticators"
 
@@ -167,11 +266,11 @@ class MfaClient:
             async with self._get_http_client() as client:
                 response = await client.get(
                     url,
-                    auth=BearerAuth(mfa_token)
+                    auth=BearerAuth(context.mfa_token)
                 )
 
                 if response.status_code != 200:
-                    error_data = response.json()
+                    error_data = self._parse_error_body(response)
                     raise MfaListAuthenticatorsError(
                         error_data.get("error_description", "Failed to list authenticators"),
                         error_data
@@ -184,8 +283,8 @@ class MfaClient:
             raise
         except Exception as e:
             raise MfaListAuthenticatorsError(
-                f"Unexpected error listing authenticators: {str(e)}"
-            )
+                "Unexpected error listing authenticators"
+            ) from e
 
     async def enroll_authenticator(
         self,
@@ -207,7 +306,10 @@ class MfaClient:
         Raises:
             MfaEnrollmentError: When enrollment fails.
         """
-        mfa_token = options["mfa_token"]
+        mfa_token = options.get("mfa_token")
+        if not mfa_token:
+            raise MfaTokenInvalidError()
+        context = self.decrypt_mfa_token(mfa_token)
         factor_type = options["factor_type"]
         base_url = await self._resolve_base_url(store_options)
         url = f"{base_url}/mfa/associate"
@@ -243,12 +345,12 @@ class MfaClient:
                 response = await client.post(
                     url,
                     json=body,
-                    auth=BearerAuth(mfa_token),
+                    auth=BearerAuth(context.mfa_token),
                     headers={"Content-Type": "application/json"}
                 )
 
                 if response.status_code != 200:
-                    error_data = response.json()
+                    error_data = self._parse_error_body(response)
                     raise MfaEnrollmentError(
                         error_data.get("error_description", "Failed to enroll authenticator"),
                         error_data
@@ -270,8 +372,8 @@ class MfaClient:
             raise
         except Exception as e:
             raise MfaEnrollmentError(
-                f"Unexpected error enrolling authenticator: {str(e)}"
-            )
+                "Unexpected error enrolling authenticator"
+            ) from e
 
     async def challenge_authenticator(
         self,
@@ -292,7 +394,10 @@ class MfaClient:
         Raises:
             MfaChallengeError: When the challenge fails.
         """
-        mfa_token = options["mfa_token"]
+        mfa_token = options.get("mfa_token")
+        if not mfa_token:
+            raise MfaTokenInvalidError()
+        context = self.decrypt_mfa_token(mfa_token)
         factor_type = options["factor_type"]
         base_url = await self._resolve_base_url(store_options)
         url = f"{base_url}/mfa/challenge"
@@ -308,7 +413,7 @@ class MfaClient:
             )
 
         body: dict[str, Any] = {
-            "mfa_token": mfa_token,
+            "mfa_token": context.mfa_token,
             "client_id": self._client_id,
             "client_secret": self._client_secret,
             "challenge_type": challenge_type
@@ -326,7 +431,7 @@ class MfaClient:
                 )
 
                 if response.status_code != 200:
-                    error_data = response.json()
+                    error_data = self._parse_error_body(response)
                     raise MfaChallengeError(
                         error_data.get("error_description", "Failed to challenge authenticator"),
                         error_data
@@ -339,13 +444,14 @@ class MfaClient:
             raise
         except Exception as e:
             raise MfaChallengeError(
-                f"Unexpected error challenging authenticator: {str(e)}"
-            )
+                "Unexpected error challenging authenticator"
+            ) from e
 
     async def verify(
         self,
         options: dict[str, Any],
-        store_options: Optional[dict[str, Any]] = None
+        store_options: Optional[dict[str, Any]] = None,
+        dpop_key: Optional["jwk.JWK"] = None,
     ) -> MfaVerifyResponse:
         """
         Verifies an MFA code and completes authentication.
@@ -365,21 +471,27 @@ class MfaClient:
                 - '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).
+            dpop_key: Optional EC P-256 JWK to DPoP-bind the token. Pass the same
+                key used at login (e.g. given to signin_with_passkey) to preserve
+                the sender constraint through step-up. Never stored by the SDK.
 
         Returns:
             MfaVerifyResponse with access_token, token_type, etc.
 
         Raises:
-            MfaVerifyError: When verification fails.
+            MfaVerifyError: When verification fails, or when dpop_key was supplied
+                but the server returned an unbound (Bearer) token.
             MfaRequiredError: When chained MFA is required.
         """
-        mfa_token = options["mfa_token"]
+        mfa_token = options.get("mfa_token")
+        if not mfa_token:
+            raise MfaTokenInvalidError()
+        context = self.decrypt_mfa_token(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
+            "mfa_token": context.mfa_token
         }
 
         if "otp" in options:
@@ -403,28 +515,44 @@ class MfaClient:
             token_endpoint = f"{base_url}/oauth/token"
 
             async with self._get_http_client() as client:
+                headers = {"Content-Type": "application/x-www-form-urlencoded"}
+                if dpop_key is not None:
+                    headers["DPoP"] = make_dpop_proof_for_token_endpoint(
+                        dpop_key, "POST", token_endpoint
+                    )
                 response = await client.post(
                     token_endpoint,
                     data=body,
-                    headers={"Content-Type": "application/x-www-form-urlencoded"}
+                    headers=headers
                 )
 
+                # Rebuild the proof with the nonce and retry once.
+                if (
+                    dpop_key is not None
+                    and response.status_code in (400, 401)
+                    and response.headers.get("DPoP-Nonce")
+                ):
+                    nonce = response.headers["DPoP-Nonce"]
+                    headers["DPoP"] = make_dpop_proof_for_token_endpoint(
+                        dpop_key, "POST", token_endpoint, nonce=nonce
+                    )
+                    response = await client.post(
+                        token_endpoint,
+                        data=body,
+                        headers=headers
+                    )
+
                 if response.status_code != 200:
-                    error_data = response.json()
+                    error_data = self._parse_error_body(response)
 
-                    # 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
+                        # Chained MFA: re-encrypt the new token with the original
+                        # audience/scope from the incoming context before raising.
+                        await self._raise_mfa_required(
+                            error_data,
+                            audience=context.audience,
+                            scope=context.scope,
+                            default_description="Additional MFA factor required",
                         )
 
                     raise MfaVerifyError(
@@ -435,11 +563,23 @@ class MfaClient:
                 token_response = response.json()
                 verify_response = MfaVerifyResponse(**token_response)
 
-                # Persist tokens to state store if requested
+                # Reject a Bearer downgrade when a DPoP token was requested
+                # (RFC 9449: a bound token has token_type "DPoP").
+                token_is_dpop = verify_response.token_type.lower() == "dpop"
+                if dpop_key is not None and not token_is_dpop:
+                    raise MfaVerifyError(
+                        "DPoP token binding failed: expected token_type 'DPoP', "
+                        f"got '{verify_response.token_type}'"
+                    )
+
+                # Clear the in-progress MFA state after successful verification.
+                if self._state_store:
+                    await self._state_store.delete(MFA_PENDING_IDENTIFIER, store_options)
+
                 if options.get("persist") and self._state_store:
                     await self._persist_mfa_tokens(
                         verify_response=verify_response,
-                        options=options,
+                        options={**options, "audience": options.get("audience") or context.audience, "scope": options.get("scope") or context.scope},
                         store_options=store_options
                     )
 
@@ -449,8 +589,8 @@ class MfaClient:
             raise
         except Exception as e:
             raise MfaVerifyError(
-                f"Unexpected error during MFA verification: {str(e)}"
-            )
+                "Unexpected error during MFA verification"
+            ) from e
 
     async def _persist_mfa_tokens(
         self,
@@ -524,5 +664,5 @@ class MfaClient:
             raise
         except Exception as e:
             raise MfaVerifyError(
-                f"Failed to persist MFA tokens to state store: {str(e)}"
-            )
+                "Failed to persist MFA tokens to state store"
+            ) from e