fix: distinguish expired ID tokens and make MFA token TTL configurable

Author: rmad17

examples/Passwordless.md

@@ -377,6 +377,7 @@ Because a 429 that carries an explicit Auth0 `error` reports that server code, `
 - `invalid_grant` - the OTP is invalid, expired, or already used
 - `invalid_issuer` - returned ID token issuer does not match your configured Auth0 domain
 - `invalid_audience` - returned ID token audience does not match the SDK client
+- `token_expired` - the returned ID token's signature has already expired
 - `discovery_error` - the SDK could not load authorization server metadata
 - `passwordless_start_failed` - SDK-side start failure
 - `passwordless_verify_failed` - SDK-side verify failure

src/auth0_server_python/auth_server/mfa_client.py

@@ -29,6 +29,7 @@
 )
 from auth0_server_python.encryption.encrypt import decrypt, encrypt
 from auth0_server_python.error import (
+    ConfigurationError,
     DomainResolverError,
     MfaChallengeError,
     MfaEnrollmentError,
@@ -71,6 +72,7 @@ def __init__(
         session_establisher: Optional[
             Callable[..., Awaitable[None]]
         ] = None,
+        mfa_token_ttl: int = DEFAULT_MFA_TOKEN_TTL,
     ):
         if callable(domain):
             self._domain = None
@@ -85,6 +87,9 @@ def __init__(
         self._state_identifier = state_identifier
         self._headers = headers or {}
         self._session_establisher = session_establisher
+        if mfa_token_ttl <= 0:
+            raise ConfigurationError("mfa_token_ttl must be a positive number of seconds")
+        self._mfa_token_ttl = mfa_token_ttl
 
     def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
         """Return an httpx.AsyncClient with default headers injected."""
@@ -142,7 +147,7 @@ def decrypt_mfa_token(self, encrypted_token: str) -> MfaTokenContext:
             raise MfaTokenInvalidError()
 
         elapsed = int(time.time()) - context.created_at
-        if elapsed > DEFAULT_MFA_TOKEN_TTL:
+        if elapsed > self._mfa_token_ttl:
             raise MfaTokenExpiredError()
 
         return context

src/auth0_server_python/auth_server/passwordless_client.py

@@ -421,8 +421,14 @@ async def _verify_id_token(
                 "ID token audience mismatch. Ensure your client_id is configured correctly.",
                 e,
             )
+        except jwt.ExpiredSignatureError as e:
+            raise PasswordlessVerifyError(
+                PasswordlessErrorCode.TOKEN_EXPIRED,
+                f"ID token has expired: {str(e)}",
+                e,
+            )
         except jwt.InvalidTokenError as e:
-            # Covers expired signature, bad signature, and other token defects.
+            # Covers bad signature and other token defects.
             raise PasswordlessVerifyError(
                 PasswordlessErrorCode.VERIFY_FAILED,
                 f"ID token verification failed: {str(e)}",

src/auth0_server_python/auth_server/server_client.py

@@ -20,7 +20,7 @@
 from pydantic import ValidationError
 
 from auth0_server_python.auth_schemes.dpop_auth import make_dpop_proof_for_token_endpoint
-from auth0_server_python.auth_server.mfa_client import MfaClient
+from auth0_server_python.auth_server.mfa_client import DEFAULT_MFA_TOKEN_TTL, MfaClient
 from auth0_server_python.auth_server.my_account_client import MyAccountClient
 from auth0_server_python.auth_server.passwordless_client import PasswordlessClient
 from auth0_server_python.auth_types import (
@@ -125,6 +125,7 @@ def __init__(
         authorization_params: Optional[dict[str, Any]] = None,
         pushed_authorization_requests: bool = False,
         organization: Optional[str] = None,
+        mfa_token_ttl: int = DEFAULT_MFA_TOKEN_TTL,
     ):
         """
         Initialize the Auth0 server client.
@@ -144,6 +145,13 @@ def __init__(
             organization: Default organization for all login flows from this client.
                 Can be an org ID (e.g. 'org_abc123') or an org name (e.g. 'acme-corp').
                 Per-login values passed in StartInteractiveLoginOptions always override this.
+            mfa_token_ttl: Seconds an encrypted MFA token remains valid before
+                `mfa.verify()`/`mfa.challenge_authenticator()` reject it as expired.
+                Defaults to 300 (5 minutes). Increase for authenticator flows that
+                need more time (e.g. OOB push approval on a slow connection).
+
+        Raises:
+            ConfigurationError: If `mfa_token_ttl` is not a positive number of seconds.
         """
         if not secret:
             raise MissingRequiredArgumentError("secret")
@@ -216,6 +224,7 @@ def __init__(
             state_identifier=self._state_identifier,
             headers=self._telemetry_headers,
             session_establisher=self._establish_session_from_mfa_verify_response,
+            mfa_token_ttl=mfa_token_ttl,
         )
 
         # Initialize Passwordless client (composes this client)
@@ -721,6 +730,8 @@ async def _establish_session_from_mfa_verify_response(
             raise MfaVerifyError(
                 "ID token audience mismatch. Ensure your client_id is configured correctly."
             ) from e
+        except jwt.ExpiredSignatureError as e:
+            raise MfaVerifyError(f"ID token has expired: {str(e)}") from e
         except jwt.InvalidTokenError as e:
             raise MfaVerifyError(f"ID token verification failed: {str(e)}") from e
 

src/auth0_server_python/error/__init__.py

@@ -409,6 +409,7 @@ class PasswordlessErrorCode:
     INVALID_GRANT = "invalid_grant"
     INVALID_ISSUER = "invalid_issuer"
     INVALID_AUDIENCE = "invalid_audience"
+    TOKEN_EXPIRED = "token_expired"
     DISCOVERY_ERROR = "discovery_error"
     # SDK-side
     START_FAILED = "passwordless_start_failed"

src/auth0_server_python/tests/test_mfa_client.py

@@ -18,6 +18,7 @@
     OtpEnrollmentResponse,
 )
 from auth0_server_python.error import (
+    ConfigurationError,
     DomainResolverError,
     MfaChallengeError,
     MfaEnrollmentError,
@@ -195,6 +196,34 @@ def test_decrypt_expired_token_raises(self, mocker):
         with pytest.raises(MfaTokenExpiredError):
             client.decrypt_mfa_token(encrypted)
 
+    def test_custom_mfa_token_ttl_is_honored(self, mocker):
+        client = MfaClient(
+            domain=DOMAIN,
+            client_id=CLIENT_ID,
+            client_secret=CLIENT_SECRET,
+            secret=SECRET,
+            mfa_token_ttl=10,
+        )
+        mocker.patch("auth0_server_python.auth_server.mfa_client.time.time", return_value=1000)
+        encrypted = client._encrypt_mfa_token(raw_mfa_token="raw", audience="aud", scope="scope")
+
+        mocker.patch("auth0_server_python.auth_server.mfa_client.time.time", return_value=1005)
+        assert client.decrypt_mfa_token(encrypted).mfa_token == "raw"
+
+        mocker.patch("auth0_server_python.auth_server.mfa_client.time.time", return_value=1011)
+        with pytest.raises(MfaTokenExpiredError):
+            client.decrypt_mfa_token(encrypted)
+
+    def test_non_positive_mfa_token_ttl_rejected(self):
+        with pytest.raises(ConfigurationError):
+            MfaClient(
+                domain=DOMAIN,
+                client_id=CLIENT_ID,
+                client_secret=CLIENT_SECRET,
+                secret=SECRET,
+                mfa_token_ttl=0,
+            )
+
     def test_decrypt_invalid_token_raises(self):
         client = _make_client()
         with pytest.raises(MfaTokenInvalidError):

src/auth0_server_python/tests/test_passwordless_client.py

@@ -23,6 +23,7 @@
     InvalidArgumentError,
     IssuerValidationError,
     MfaRequiredError,
+    MfaVerifyError,
     MissingRequiredArgumentError,
     PasswordlessStartError,
     PasswordlessVerifyError,
@@ -662,6 +663,31 @@ async def test_verify_invalid_audience_maps_to_typed_error(self, mocker):
         assert exc.value.code == "invalid_audience"
         client._state_store.set.assert_not_awaited()
 
+    @pytest.mark.asyncio
+    async def test_verify_expired_id_token_maps_to_typed_error(self, mocker):
+        client = _make_client()
+        mocker.patch.object(client, "_get_oidc_metadata_cached", return_value=METADATA)
+        mocker.patch.object(
+            client,
+            "_get_jwks_cached",
+            return_value={"keys": [{"kty": "RSA", "kid": "k1"}]},
+        )
+        mocker.patch.object(
+            client,
+            "_verify_and_decode_jwt",
+            side_effect=jwt.ExpiredSignatureError("signature has expired"),
+        )
+        _mock_http(client, 200, {"access_token": "at", "id_token": "idt", "expires_in": 3600})
+
+        with pytest.raises(PasswordlessVerifyError) as exc:
+            await client.passwordless.verify(
+                VerifyPasswordlessOtpOptions(
+                    connection="email", email="user@example.com", verification_code="123456"
+                )
+            )
+        assert exc.value.code == "token_expired"
+        client._state_store.set.assert_not_awaited()
+
     @pytest.mark.asyncio
     async def test_client_ip_forwarded_on_verify(self, mocker):
         client = _make_client()
@@ -919,6 +945,60 @@ async def test_passwordless_mfa_verify_persist_creates_session(self, mocker):
         assert saved_state.internal.sid == "SID-MFA"
         assert saved_state.token_sets[0].access_token == "mfa_at"
 
+    @pytest.mark.asyncio
+    async def test_mfa_verify_persist_expired_id_token_maps_to_typed_error(self, mocker):
+        client = _make_client()
+        mocker.patch.object(client, "_get_oidc_metadata_cached", return_value=METADATA)
+        mocker.patch.object(
+            client,
+            "_get_jwks_cached",
+            return_value={"keys": [{"kty": "RSA", "kid": "k1"}]},
+        )
+        mocker.patch.object(
+            client,
+            "_verify_and_decode_jwt",
+            side_effect=jwt.ExpiredSignatureError("signature has expired"),
+        )
+        _mock_http(
+            client,
+            403,
+            {
+                "error": "mfa_required",
+                "error_description": "Additional factor required",
+                "mfa_token": "raw_server_mfa_token",
+            },
+        )
+
+        with pytest.raises(MfaRequiredError) as exc:
+            await client.passwordless.verify(
+                VerifyPasswordlessOtpOptions(
+                    connection="email", email="user@example.com", verification_code="123456"
+                ),
+                store_options={},
+            )
+
+        client._state_store.get = AsyncMock(return_value=None)
+        mfa_response = AsyncMock()
+        mfa_response.status_code = 200
+        mfa_response.headers = {}
+        mfa_response.json = MagicMock(
+            return_value={
+                "access_token": "mfa_at",
+                "id_token": "mfa_idt",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "scope": "openid profile email",
+            }
+        )
+        mocker.patch("httpx.AsyncClient.post", new_callable=AsyncMock, return_value=mfa_response)
+
+        with pytest.raises(MfaVerifyError, match="expired"):
+            await client.mfa.verify(
+                {"mfa_token": exc.value.mfa_token, "otp": "654321", "persist": True},
+                store_options={},
+            )
+        client._state_store.set.assert_not_awaited()
+
     @pytest.mark.asyncio
     async def test_verify_mfa_required_without_token_falls_through(self, mocker):
         # Third-party-strict / flex-commands-with-FF-off: 403 mfa_required with

src/auth0_server_python/tests/test_server_client.py

@@ -79,6 +79,31 @@ async def test_init_no_secret_raises():
     assert "secret" in str(exc.value)
 
 
+@pytest.mark.asyncio
+async def test_mfa_token_ttl_propagates_to_mfa_client():
+    """A custom mfa_token_ttl reaches the internal MfaClient, overriding the default."""
+    client = ServerClient(
+        domain="auth0.local",
+        client_id="<client_id>",
+        client_secret="<client_secret>",
+        secret="some-secret",
+        mfa_token_ttl=900,
+    )
+    assert client._mfa_client._mfa_token_ttl == 900
+
+
+@pytest.mark.asyncio
+async def test_mfa_token_ttl_non_positive_rejected():
+    with pytest.raises(ConfigurationError):
+        ServerClient(
+            domain="auth0.local",
+            client_id="<client_id>",
+            client_secret="<client_secret>",
+            secret="some-secret",
+            mfa_token_ttl=-1,
+        )
+
+
 @pytest.mark.asyncio
 async def test_start_interactive_login_no_redirect_uri(mocker):
     client = ServerClient(