feat: Add Custom Token Exchange Support

Author: tanya732

.fernignore

@@ -32,14 +32,12 @@ src/main/java/com/auth0/client/LoggingOptions.java
 # TokenProvider interface (shared between Fern-generated Management API and auth0-provided Authentication API)
 src/main/java/com/auth0/client/mgmt/TokenProvider.java
 
-# Test infrastructure from auth0-real
-src/test/java/com/auth0/net/
-src/test/java/com/auth0/exception/
-src/test/java/com/auth0/utils/
-src/test/java/com/auth0/json/
+# Shared test infrastructure for the Authentication API tests (manually maintained from auth0-real)
+src/test/java/com/auth0/client/MockServer.java
+src/test/java/com/auth0/client/RecordedRequestMatcher.java
+src/test/java/com/auth0/client/UrlMatcher.java
+src/test/java/com/auth0/AssertsUtil.java
 src/test/resources/auth/
-src/test/resources/keys/
-src/test/resources/mgmt/
 src/test/resources/mockito-extensions/
 src/test/java/com/auth0/client/legacy/
 

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

@@ -57,6 +57,8 @@ public class AuthAPI {
     private static final String KEY_MFA_TOKEN = "mfa_token";
     private static final String KEY_CLIENT_ASSERTION = "client_assertion";
     private static final String KEY_CLIENT_ASSERTION_TYPE = "client_assertion_type";
+    private static final String KEY_SUBJECT_TOKEN = "subject_token";
+    private static final String KEY_SUBJECT_TOKEN_TYPE = "subject_token_type";
     private static final String PATH_OAUTH = "oauth";
     private static final String PATH_TOKEN = "token";
     private static final String PATH_DBCONNECTIONS = "dbconnections";
@@ -800,6 +802,44 @@ public TokenRequest requestToken(String audience, String org) {
         return request;
     }
 
+    /**
+     * Creates a request to exchange an external subject token for Auth0 tokens using the
+     * {@code urn:ietf:params:oauth:grant-type:token-exchange} grant (Custom Token Exchange).
+     * A Token Exchange Profile that maps the given {@code subjectTokenType} must be configured on the tenant, and
+     * client authentication (client secret or client assertion) is required.
+     * <pre>
+     * {@code
+     * try {
+     *      TokenHolder result = authAPI.exchangeToken("test-user123-john@example.com", "urn:mycompany:m2m-test-token")
+     *          .setAudience("https://myapi.me.auth0.com/users")
+     *          .setScope("openid profile email")
+     *          .execute()
+     *          .getBody();
+     * } catch (Auth0Exception e) {
+     *      //Something happened
+     * }
+     * }
+     * </pre>
+     *
+     * @see <a href="https://auth0.com/docs/authenticate/custom-token-exchange">Custom Token Exchange documentation</a>
+     * @param subjectToken the external token representing the identity of the subject. Must not be null.
+     * @param subjectTokenType an identifier for the type of the {@code subjectToken}, matching a configured Token
+     *                         Exchange Profile (for example {@code urn:mycompany:m2m-test-token}). Must not be null.
+     * @return a Request to configure and execute.
+     */
+    public TokenRequest exchangeToken(String subjectToken, String subjectTokenType) {
+        Asserts.assertNotNull(subjectToken, "subject token");
+        Asserts.assertNotNull(subjectTokenType, "subject token type");
+
+        TokenRequest request = new TokenRequest(client, getTokenUrl());
+        request.addParameter(KEY_CLIENT_ID, clientId);
+        request.addParameter(KEY_GRANT_TYPE, "urn:ietf:params:oauth:grant-type:token-exchange");
+        request.addParameter(KEY_SUBJECT_TOKEN, subjectToken);
+        request.addParameter(KEY_SUBJECT_TOKEN_TYPE, subjectTokenType);
+        addClientAuthentication(request, true);
+        return request;
+    }
+
     /**
      * Creates a request to revoke an existing Refresh Token.
      * Confidential clients (Regular Web Apps) <strong>must</strong> have a client secret configured on this {@code AuthAPI} instance.

src/test/java/com/auth0/AssertsUtil.java

@@ -0,0 +1,20 @@
+package com.auth0;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.function.Executable;
+
+public class AssertsUtil {
+
+    public static <T extends Throwable> T verifyThrows(Class<T> expectedType, Executable executable) {
+        return assertThrows(expectedType, executable);
+    }
+
+    public static <T extends Throwable> T verifyThrows(Class<T> expectedType, Executable executable, String message) {
+        T result = assertThrows(expectedType, executable);
+        assertThat(result.getMessage(), is(message));
+        return result;
+    }
+}