Keep previous method but deprecate it

Author: JoaoSouMoreira

src/main/java/com/auth0/client/auth/AuthAPI.java

@@ -1413,6 +1413,54 @@ public Request<CreatedOtpResponse> addOtpAuthenticator(String mfaToken) {
      * @param mfaToken The token received from mfa_required error. Must not be null.
      * @param oobChannels The type of OOB channels supported by the client. Must not be null.
      * @param phoneNumber The phone number for "sms" or "voice" channels. May be null if not using "sms" or "voice".
+     * @return a Request to execute.
+     * @see <a href="https://auth0.com/docs/api/authentication#add-an-authenticator">Add an Authenticator API documentation</a>
+     * @deprecated Use {@linkplain #addOobAuthenticator(String, List, String, String)} instead.
+     */
+    @Deprecated
+    public Request<CreatedOobResponse> addOobAuthenticator(String mfaToken, List<String> oobChannels, String phoneNumber) {
+        Asserts.assertNotNull(mfaToken, "mfa token");
+        Asserts.assertNotNull(oobChannels, "OOB channels");
+
+        String url = baseUrl
+            .newBuilder()
+            .addPathSegment("mfa")
+            .addPathSegment("associate")
+            .build()
+            .toString();
+
+        BaseRequest<CreatedOobResponse> request = new BaseRequest<>(client, null, url, HttpMethod.POST, new TypeReference<CreatedOobResponse>() {
+        });
+
+        request.addParameter("authenticator_types", Collections.singletonList("oob"));
+        request.addParameter("oob_channels", oobChannels);
+        request.addParameter(KEY_CLIENT_ID, clientId);
+        if (phoneNumber != null) {
+            request.addParameter("phone_number", phoneNumber);
+        }
+        addClientAuthentication(request, false);
+        request.addHeader("Authorization", "Bearer " + mfaToken);
+        return request;
+    }
+
+    /**
+     * Associates or adds a new OOB authenticator for multi-factor authentication (MFA).
+     * Confidential clients (Regular Web Apps) <strong>must</strong> have a client secret configured on this {@code AuthAPI} instance.
+     * <pre>
+     * {@code
+     * try {
+     *      CreatedOobResponse result = authAPI.addOobAuthenticator("the-mfa-token", Arrays.asList("sms", "email"), "phone-number", "email-address")
+     *          .execute()
+     *          .getBody();
+     * } catch (Auth0Exception e) {
+     *      //Something happened
+     * }
+     * }
+     * </pre>
+     *
+     * @param mfaToken The token received from mfa_required error. Must not be null.
+     * @param oobChannels The type of OOB channels supported by the client. Must not be null.
+     * @param phoneNumber The phone number for "sms" or "voice" channels. May be null if not using "sms" or "voice".
      * @param emailAddress The  email address for "email" channel. May be null if not using "email".
      * @return a Request to execute.
      * @see <a href="https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators#enroll-with-sms-or-voice">Enroll with SMS or voice</a>

src/test/java/com/auth0/client/auth/AuthAPITest.java

@@ -1548,20 +1548,47 @@ public void addOobAuthenticatorThrowsWhenTokenNull() {
             "'mfa token' cannot be null!");
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void addOobAuthenticatorThrowsWhenChannelsNull() {
         verifyThrows(IllegalArgumentException.class,
-            () -> api.addOobAuthenticator("mfaToken", null, null, null),
+            () -> api.addOobAuthenticator("mfaToken", null, null),
             "'OOB channels' cannot be null!");
     }
 
+    @SuppressWarnings("deprecation")
     @Test
     public void addOobAuthenticatorThrowsWhenPhoneNumberNull() {
         verifyThrows(IllegalArgumentException.class,
             () -> api.addOobAuthenticator("mfaToken", Collections.singletonList("sms"), null, null),
             "'phone number' cannot be null!");
     }
 
+    @SuppressWarnings("deprecation")
+    @Test
+    public void addOobAuthenticatorRequest() throws Exception {
+        Request<CreatedOobResponse> request = api.addOobAuthenticator("mfaToken", Collections.singletonList("sms"), "phone-number");
+
+        server.jsonResponse(AUTH_OOB_AUTHENTICATOR_RESPONSE, 200);
+        CreatedOobResponse response = request.execute().getBody();
+        RecordedRequest recordedRequest = server.takeRequest();
+
+        assertThat(recordedRequest, hasMethodAndPath(HttpMethod.POST, "/mfa/associate"));
+        assertThat(recordedRequest, hasHeader("Content-Type", "application/json"));
+
+        Map<String, Object> body = bodyFromRequest(recordedRequest);
+        assertThat(body, hasEntry("authenticator_types", Collections.singletonList("oob")));
+        assertThat(body, hasEntry("oob_channels", Collections.singletonList("sms")));
+        assertThat(body, hasEntry("phone_number", "phone-number"));
+
+        assertThat(response, is(notNullValue()));
+        assertThat(response.getAuthenticatorType(), not(emptyOrNullString()));
+        assertThat(response.getOobChannel(), not(emptyOrNullString()));
+        assertThat(response.getOobCode(), not(emptyOrNullString()));
+        assertThat(response.getBarcodeUri(), not(emptyOrNullString()));
+        assertThat(response.getRecoveryCodes(), notNullValue());
+    }
+
     @Test
     public void addOobAuthenticatorThrowsWhenEmailNull() {
         verifyThrows(IllegalArgumentException.class,
@@ -1570,7 +1597,7 @@ public void addOobAuthenticatorThrowsWhenEmailNull() {
     }
 
     @Test
-    public void addOobAuthenticatorRequest() throws Exception {
+    public void addOobAuthenticatorRequestWithEmail() throws Exception {
         Request<CreatedOobResponse> request = api.addOobAuthenticator("mfaToken", Arrays.asList("sms", "email"), "phone-number", "email-address");
 
         server.jsonResponse(AUTH_OOB_AUTHENTICATOR_RESPONSE, 200);