Feat: MCD Support (auth0#849)

Author: tanya732

.fernignore

@@ -49,6 +49,8 @@ src/main/java/com/auth0/client/ClientCredentialsTokenProvider.java
 src/main/java/com/auth0/client/ManagementApiWithTokenProvider.java
 src/main/java/com/auth0/client/TokenProvider.java
 src/main/java/com/auth0/client/interceptors/
+src/main/java/com/auth0/client/mgmt/core/CustomDomainInterceptor.java
+ src/main/java/com/auth0/client/mgmt/CustomDomainHeader.java
 
 # Custom OAuth client credentials support
 src/main/java/com/auth0/client/mgmt/core/RequestOptions.java
@@ -63,6 +65,8 @@ src/main/java/com/auth0/client/mgmt/ManagementApiBuilder.java
 src/test/java/com/auth0/client/mgmt/DynamicTokenManagementTest.java
 src/test/java/com/auth0/client/mgmt/OAuthTokenSupplierTest.java
 src/test/java/com/auth0/client/mgmt/ManagementApiBuilderTest.java
+src/test/java/com/auth0/client/mgmt/CustomDomainInterceptorTest.java
+src/test/java/com/auth0/client/mgmt/CustomDomainHeaderIntegrationTest.java
 
 # Configuration files from auth0-real
 .codecov.yml

build.gradle

@@ -22,9 +22,9 @@ logger.lifecycle("Using version ${version} for ${name} group $group")
 dependencies {
   // Core dependencies
   api 'com.squareup.okhttp3:okhttp:5.2.1'
-  api 'com.fasterxml.jackson.core:jackson-databind:2.18.6'
-  api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.6'
-  api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.6'
+  api 'com.fasterxml.jackson.core:jackson-databind:2.21.2'
+  api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.21.2'
+  api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.21.2'
 
   // Dependencies for legacy management code from auth0-real
   implementation 'com.squareup.okhttp3:logging-interceptor:5.2.1'

src/main/java/com/auth0/client/mgmt/CustomDomainHeader.java

@@ -0,0 +1,38 @@
+package com.auth0.client.mgmt;
+
+import com.auth0.client.mgmt.core.CustomDomainInterceptor;
+import com.auth0.client.mgmt.core.RequestOptions;
+
+/**
+ * Convenience helper for creating per-request custom domain overrides.
+ *
+ * <p>Use this to override the global custom domain for a specific API call.
+ * The header is only sent to whitelisted endpoints that generate user-facing links.
+ *
+ * <p>Example usage:
+ * <pre>{@code
+ * // Override the custom domain for a specific request
+ * client.users().list(CustomDomainHeader.of("other.mycompany.com"));
+ *
+ * // Use with tickets
+ * client.tickets().createEmailVerification(request, CustomDomainHeader.of("login.mycompany.com"));
+ * }</pre>
+ *
+ * @see ManagementApiBuilder#customDomain(String) for setting a global custom domain
+ */
+public final class CustomDomainHeader {
+
+    private CustomDomainHeader() {}
+
+    /**
+     * Creates a {@link RequestOptions} instance with the Auth0-Custom-Domain header set.
+     *
+     * @param domain The custom domain to use (e.g., "login.mycompany.com")
+     * @return RequestOptions with the custom domain header configured
+     */
+    public static RequestOptions of(String domain) {
+        return RequestOptions.builder()
+                .addHeader(CustomDomainInterceptor.HEADER_NAME, domain)
+                .build();
+    }
+}

src/main/java/com/auth0/client/mgmt/ManagementApiBuilder.java

@@ -4,6 +4,7 @@
 package com.auth0.client.mgmt;
 
 import com.auth0.client.mgmt.core.ClientOptions;
+import com.auth0.client.mgmt.core.CustomDomainInterceptor;
 import com.auth0.client.mgmt.core.Environment;
 import com.auth0.client.mgmt.core.OAuthTokenSupplier;
 import java.util.HashMap;
@@ -25,6 +26,8 @@ public class ManagementApiBuilder {
 
     private OkHttpClient httpClient;
 
+    private String customDomain = null;
+
     // Domain-based initialization fields
     private String domain = null;
     private String clientId = null;
@@ -107,6 +110,40 @@ public ManagementApiBuilder audience(String audience) {
         return this;
     }
 
+    /**
+     * Sets the custom domain for the Auth0-Custom-Domain header.
+     * When configured, the header is automatically sent on whitelisted API endpoints
+     * that generate user-facing links (email verification, password change, invitations, etc.).
+     *
+     * <p>The header is only sent to whitelisted endpoints:
+     * <ul>
+     *   <li>{@code /jobs/verification-email}</li>
+     *   <li>{@code /tickets/email-verification}</li>
+     *   <li>{@code /tickets/password-change}</li>
+     *   <li>{@code /organizations/{id}/invitations}</li>
+     *   <li>{@code /users} and {@code /users/{id}}</li>
+     *   <li>{@code /guardian/enrollments/ticket}</li>
+     *   <li>{@code /self-service-profiles/{id}/sso-ticket}</li>
+     * </ul>
+     *
+     * <p>Example:
+     * <pre>{@code
+     * ManagementApi client = ManagementApi.builder()
+     *     .domain("your-tenant.auth0.com")
+     *     .token("YOUR_TOKEN")
+     *     .customDomain("login.mycompany.com")
+     *     .build();
+     * }</pre>
+     *
+     * @param customDomain The custom domain (e.g., "login.mycompany.com")
+     * @return This builder for method chaining
+     * @see CustomDomainHeader#of(String) for per-request custom domain overrides
+     */
+    public ManagementApiBuilder customDomain(String customDomain) {
+        this.customDomain = customDomain;
+        return this;
+    }
+
     /**
      * Sets the timeout (in seconds) for the client. Defaults to 60 seconds.
      */
@@ -154,6 +191,10 @@ protected ClientOptions buildClientOptions() {
         for (Map.Entry<String, String> header : this.customHeaders.entrySet()) {
             builder.addHeader(header.getKey(), header.getValue());
         }
+        if (this.customDomain != null) {
+            builder.addHeader(CustomDomainInterceptor.HEADER_NAME, this.customDomain);
+            builder.addInterceptor(new CustomDomainInterceptor());
+        }
         setAdditional(builder);
         return builder.build();
     }

src/main/java/com/auth0/client/mgmt/core/ClientOptions.java

@@ -4,11 +4,14 @@
 package com.auth0.client.mgmt.core;
 
 import com.auth0.net.Telemetry;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
+import okhttp3.Interceptor;
 import okhttp3.OkHttpClient;
 
 public final class ClientOptions {
@@ -100,6 +103,8 @@ public static class Builder {
 
         private final Map<String, Supplier<String>> headerSuppliers = new HashMap<>();
 
+        private final List<Interceptor> interceptors = new ArrayList<>();
+
         private int maxRetries = 2;
 
         private Optional<Integer> timeout = Optional.empty();
@@ -150,6 +155,14 @@ public Builder httpClient(OkHttpClient httpClient) {
             return this;
         }
 
+        /**
+         * Add an OkHttp interceptor to the client.
+         */
+        public Builder addInterceptor(Interceptor interceptor) {
+            this.interceptors.add(interceptor);
+            return this;
+        }
+
         public ClientOptions build() {
             OkHttpClient.Builder httpClientBuilder =
                     this.httpClient != null ? this.httpClient.newBuilder() : new OkHttpClient.Builder();
@@ -169,6 +182,10 @@ public ClientOptions build() {
                         .addInterceptor(new RetryInterceptor(this.maxRetries));
             }
 
+            for (Interceptor interceptor : this.interceptors) {
+                httpClientBuilder.addInterceptor(interceptor);
+            }
+
             this.httpClient = httpClientBuilder.build();
             this.timeout = Optional.of(httpClient.callTimeoutMillis() / 1000);
 

src/main/java/com/auth0/client/mgmt/core/CustomDomainInterceptor.java

@@ -0,0 +1,61 @@
+package com.auth0.client.mgmt.core;
+
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.List;
+import java.util.regex.Pattern;
+import okhttp3.Interceptor;
+import okhttp3.Request;
+import okhttp3.Response;
+
+/**
+ * OkHttp interceptor that enforces the Auth0-Custom-Domain header whitelist.
+ *
+ * <p>The Auth0-Custom-Domain header is only sent to specific API endpoints that generate
+ * user-facing links (email verification, password change, invitations, etc.). This interceptor
+ * strips the header from requests to non-whitelisted paths.
+ *
+ * <p>Whitelisted endpoints:
+ * <ul>
+ *   <li>{@code /jobs/verification-email}</li>
+ *   <li>{@code /tickets/email-verification}</li>
+ *   <li>{@code /tickets/password-change}</li>
+ *   <li>{@code /organizations/{id}/invitations}</li>
+ *   <li>{@code /users} and {@code /users/{id}}</li>
+ *   <li>{@code /guardian/enrollments/ticket}</li>
+ *   <li>{@code /self-service-profiles/{id}/sso-ticket}</li>
+ * </ul>
+ */
+public class CustomDomainInterceptor implements Interceptor {
+
+    public static final String HEADER_NAME = "Auth0-Custom-Domain";
+
+    private static final List<Pattern> WHITELISTED_PATHS = Arrays.asList(
+            Pattern.compile(".*/jobs/verification-email$"),
+            Pattern.compile(".*/tickets/email-verification$"),
+            Pattern.compile(".*/tickets/password-change$"),
+            Pattern.compile(".*/organizations/[^/]+/invitations(/[^/]+)?$"),
+            Pattern.compile(".*/users(/[^/]+)?$"),
+            Pattern.compile(".*/guardian/enrollments/ticket$"),
+            Pattern.compile(".*/self-service-profiles/[^/]+/sso-ticket(/[^/]+/revoke)?$"));
+
+    @Override
+    public Response intercept(Chain chain) throws IOException {
+        Request request = chain.request();
+
+        if (request.header(HEADER_NAME) != null && !isWhitelisted(request.url().encodedPath())) {
+            request = request.newBuilder().removeHeader(HEADER_NAME).build();
+        }
+
+        return chain.proceed(request);
+    }
+
+    public static boolean isWhitelisted(String path) {
+        for (Pattern pattern : WHITELISTED_PATHS) {
+            if (pattern.matcher(path).matches()) {
+                return true;
+            }
+        }
+        return false;
+    }
+}