feat(mfa): Update MFA API to use 'factor_type' instead of 'authenticator_types' for enrollment and challenge

Author: subhankarmaiti

examples/MFA.md

@@ -173,7 +173,7 @@ Enroll an OTP authenticator (Google Authenticator, Microsoft Authenticator, etc.
 try:
     enrollment = await server_client.mfa.enroll_authenticator({
         "mfa_token": mfa_token,
-        "authenticator_types": "otp"
+        "factor_type": "otp"
     })
 
     # Display QR code to user
@@ -192,8 +192,7 @@ Enroll an SMS authenticator:
 try:
     enrollment = await server_client.mfa.enroll_authenticator({
         "mfa_token": mfa_token,
-        "authenticator_types": "sms",
-        "oob_channels": "sms",
+        "factor_type": "sms",
         "phone_number": "+12025551234"  # E.164 format
     })
 
@@ -213,8 +212,7 @@ Enroll a voice call authenticator:
 try:
     enrollment = await server_client.mfa.enroll_authenticator({
         "mfa_token": mfa_token,
-        "authenticator_types": "voice",
-        "oob_channels": "voice",
+        "factor_type": "voice",
         "phone_number": "+12025551234"  # E.164 format
     })
 
@@ -233,8 +231,7 @@ Enroll an email authenticator:
 try:
     enrollment = await server_client.mfa.enroll_authenticator({
         "mfa_token": mfa_token,
-        "authenticator_types": "email",
-        "oob_channels": "email",
+        "factor_type": "email",
         "email": "user@example.com"
     })
 
@@ -255,7 +252,7 @@ After enrolling an authenticator, or when the user has existing authenticators,
 try:
     challenge = await server_client.mfa.challenge_authenticator({
         "mfa_token": mfa_token,
-        "challenge_type": "oob",
+        "factor_type": "sms",
         "authenticator_id": "sms|dev_xxx"
     })
 
@@ -273,7 +270,7 @@ except Exception as error:
 try:
     challenge = await server_client.mfa.challenge_authenticator({
         "mfa_token": mfa_token,
-        "challenge_type": "oob",
+        "factor_type": "email",
         "authenticator_id": "email|dev_xxx"
     })
 
@@ -293,7 +290,7 @@ except Exception as error:
 try:
     challenge = await server_client.mfa.challenge_authenticator({
         "mfa_token": mfa_token,
-        "challenge_type": "otp",
+        "factor_type": "otp",
         "authenticator_id": "otp|dev_xxx"
     })
 
@@ -443,7 +440,7 @@ async def handle_mfa_enrollment_flow(server_client, mfa_token):
         # User selects OTP
         enrollment = await server_client.mfa.enroll_authenticator({
             "mfa_token": mfa_token,
-            "authenticator_types": "otp"
+            "factor_type": "otp"
         })
 
         # Display QR code to user
@@ -491,11 +488,9 @@ async def handle_mfa_challenge_flow(server_client, mfa_token):
         selected_auth = authenticators[selected_index]
 
         # Initiate challenge
-        challenge_type = "otp" if selected_auth.authenticator_type == "otp" else "oob"
-        
         challenge = await server_client.mfa.challenge_authenticator({
             "mfa_token": mfa_token,
-            "challenge_type": challenge_type,
+            "factor_type": selected_auth.authenticator_type,
             "authenticator_id": selected_auth.id
         })
 
@@ -597,7 +592,7 @@ async def handle_mfa_with_error_handling(server_client):
             # Initiate challenge
             challenge = await server_client.mfa.challenge_authenticator({
                 "mfa_token": mfa_token,
-                "challenge_type": "oob",
+                "factor_type": "sms",
                 "authenticator_id": authenticators[0].id
             })
         except ApiError as challenge_error:

src/auth0_server_python/auth_server/mfa_client.py

@@ -155,8 +155,8 @@ async def enroll_authenticator(
 
         Args:
             options: Dict containing enrollment parameters.
-                Required: 'mfa_token', 'authenticator_types'.
-                Optional: 'oob_channels', 'phone_number', 'email'.
+                Required: 'mfa_token', 'factor_type' (otp, sms, voice, email).
+                Optional: 'phone_number', 'email'.
 
         Returns:
             OtpEnrollmentResponse or OobEnrollmentResponse.
@@ -165,15 +165,28 @@ async def enroll_authenticator(
             MfaEnrollmentError: When enrollment fails.
         """
         mfa_token = options["mfa_token"]
+        factor_type = options["factor_type"]
         url = f"{self._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"]:
+            authenticator_type = "oob"
+            oob_channels = factor_type
+        else:
+            raise MfaEnrollmentError(
+                f"Unsupported factor_type: {factor_type}. Supported types: otp, sms, voice, email"
+            )
+
         # Build API request body
         body: dict[str, Any] = {
-            "authenticator_types": options["authenticator_types"]
+            "authenticator_types": authenticator_type
         }
 
-        if "oob_channels" in options:
-            body["oob_channels"] = options["oob_channels"]
+        if oob_channels:
+            body["oob_channels"] = oob_channels
 
         if "phone_number" in options and options["phone_number"]:
             body["phone_number"] = options["phone_number"]
@@ -224,7 +237,7 @@ async def challenge_authenticator(
         Initiates an MFA challenge for user verification.
 
         Args:
-            options: Dict containing 'mfa_token', 'challenge_type',
+            options: Dict containing 'mfa_token', 'factor_type' (otp, sms, voice, email),
                 and optionally 'authenticator_id'.
 
         Returns:
@@ -234,12 +247,23 @@ async def challenge_authenticator(
             MfaChallengeError: When the challenge fails.
         """
         mfa_token = options["mfa_token"]
+        factor_type = options["factor_type"]
         url = f"{self._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"]:
+            challenge_type = "oob"
+        else:
+            raise MfaChallengeError(
+                f"Unsupported factor_type: {factor_type}. Supported types: otp, sms, voice, email"
+            )
+
         body: dict[str, Any] = {
             "mfa_token": mfa_token,
             "client_id": self._client_id,
-            "challenge_type": options["challenge_type"]
+            "challenge_type": challenge_type
         }
 
         if "authenticator_id" in options and options["authenticator_id"]:

src/auth0_server_python/tests/test_mfa_client.py

@@ -189,7 +189,7 @@ async def test_enroll_otp_success(self, mocker):
 
         result = await client.enroll_authenticator({
             "mfa_token": "tok",
-            "authenticator_types": ["otp"]
+            "factor_type": "otp"
         })
         assert isinstance(result, OtpEnrollmentResponse)
         assert result.secret == "JBSWY3DPEHPK3PXP"
@@ -210,8 +210,7 @@ async def test_enroll_sms_oob_success(self, mocker):
 
         result = await client.enroll_authenticator({
             "mfa_token": "tok",
-            "authenticator_types": ["oob"],
-            "oob_channels": ["sms"],
+            "factor_type": "sms",
             "phone_number": "+1234567890"
         })
         assert isinstance(result, OobEnrollmentResponse)
@@ -231,8 +230,7 @@ async def test_enroll_email_oob_success(self, mocker):
 
         result = await client.enroll_authenticator({
             "mfa_token": "tok",
-            "authenticator_types": ["oob"],
-            "oob_channels": ["email"],
+            "factor_type": "email",
             "email": "user@example.com"
         })
         assert isinstance(result, OobEnrollmentResponse)
@@ -254,8 +252,7 @@ async def test_enroll_push_auth0_channel_success(self, mocker):
 
         result = await client.enroll_authenticator({
             "mfa_token": "tok",
-            "authenticator_types": ["oob"],
-            "oob_channels": ["auth0"]
+            "factor_type": "sms"
         })
         assert isinstance(result, OobEnrollmentResponse)
         assert result.oob_channel == "auth0"
@@ -274,7 +271,7 @@ async def test_enroll_api_error(self, mocker):
         with pytest.raises(MfaEnrollmentError) as exc:
             await client.enroll_authenticator({
                 "mfa_token": "tok",
-                "authenticator_types": ["otp"]
+                "factor_type": "otp"
             })
         assert "Bad enrollment request" in str(exc.value)
 
@@ -291,9 +288,9 @@ async def test_enroll_unexpected_authenticator_type(self, mocker):
         with pytest.raises(MfaEnrollmentError) as exc:
             await client.enroll_authenticator({
                 "mfa_token": "tok",
-                "authenticator_types": ["unknown_type"]
+                "factor_type": "unknown"
             })
-        assert "Unexpected authenticator type" in str(exc.value)
+        assert "Unsupported factor_type" in str(exc.value)
 
 
 # ── delete_authenticator ─────────────────────────────────────────────────────
@@ -313,7 +310,7 @@ async def test_challenge_otp_success(self, mocker):
 
         result = await client.challenge_authenticator({
             "mfa_token": "tok",
-            "challenge_type": "otp"
+            "factor_type": "otp"
         })
         assert isinstance(result, ChallengeResponse)
         assert result.challenge_type == "otp"
@@ -332,7 +329,7 @@ async def test_challenge_oob_success(self, mocker):
 
         result = await client.challenge_authenticator({
             "mfa_token": "tok",
-            "challenge_type": "oob",
+            "factor_type": "sms",
             "authenticator_id": "auth|456"
         })
         assert result.challenge_type == "oob"
@@ -352,7 +349,7 @@ async def test_challenge_api_error(self, mocker):
         with pytest.raises(MfaChallengeError) as exc:
             await client.challenge_authenticator({
                 "mfa_token": "tok",
-                "challenge_type": "otp"
+                "factor_type": "otp"
             })
         assert "Token expired" in str(exc.value)
 
@@ -371,7 +368,7 @@ async def test_challenge_expired_mfa_token(self, mocker):
         with pytest.raises(MfaChallengeError) as exc:
             await client.challenge_authenticator({
                 "mfa_token": "expired_tok",
-                "challenge_type": "otp"
+                "factor_type": "otp"
             })
         assert "mfa_token is expired" in str(exc.value)
 
@@ -390,7 +387,7 @@ async def test_challenge_email_with_authenticator_id(self, mocker):
 
         result = await client.challenge_authenticator({
             "mfa_token": "tok",
-            "challenge_type": "oob",
+            "factor_type": "email",
             "authenticator_id": "email|dev_Fvx38nHufsGL5lWI"
         })
         assert result.challenge_type == "oob"
@@ -412,7 +409,7 @@ async def test_challenge_sms_with_authenticator_id(self, mocker):
 
         result = await client.challenge_authenticator({
             "mfa_token": "tok",
-            "challenge_type": "oob",
+            "factor_type": "sms",
             "authenticator_id": "sms|dev_h1uXXoVjQ5BpU9iQ"
         })
         assert result.challenge_type == "oob"