Remove Empty files

Author: tanya732

auth0-api-java/src/main/java/com/auth0/JWTValidator.java

@@ -15,13 +15,13 @@
 import com.auth0.jwt.interfaces.DecodedJWT;
 import com.auth0.models.HttpRequestInfo;
 import com.auth0.models.RequestContext;
-import com.auth0.OidcDiscoveryFetcher;
 
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.security.interfaces.RSAPublicKey;
 import java.util.Collections;
 import java.util.List;
+import java.util.Locale;
 import java.util.stream.Collectors;
 
 /**
@@ -138,12 +138,14 @@ public DecodedJWT validateToken(String token, HttpRequestInfo httpRequestInfo) t
                 throw new VerifyAccessTokenException("Token issuer is not in the allowed list");
             }
 
-            OidcMetadata discovery = performOidcDiscovery(tokenIss);
+            OidcMetadata discovery = performOidcDiscovery(normalizedIss);
 
-            if (!tokenIss.equals(discovery.getIssuer())) {
+            if (!normalizedIss.equals(normalizeToUrl(discovery.getIssuer()))) {
                 throw new VerifyAccessTokenException("Discovery metadata issuer does not match token issuer");
             }
 
+            validateJwksUriHost(normalizedIss, discovery.getJwksUri());
+
             JwkProvider dynamicJwkProvider = getOrCreateJwkProvider(discovery.getJwksUri());
 
             Jwk jwk = dynamicJwkProvider.get(unverifiedJwt.getKeyId());
@@ -156,6 +158,8 @@ public DecodedJWT validateToken(String token, HttpRequestInfo httpRequestInfo) t
 
             return verifier.verify(token);
 
+        } catch (BaseAuthException e) {
+            throw e;
         } catch (Exception e) {
             throw new VerifyAccessTokenException("signature verification failed", e);
         }
@@ -341,10 +345,37 @@ private List<String> resolveAllowedDomains(String tokenIss, HttpRequestInfo http
         return Collections.emptyList();
     }
 
+    /**
+     * Validates that the JWKS URI host matches the issuer host.
+     * <p>
+     * Prevents a compromised OIDC discovery endpoint from redirecting JWKS
+     * fetches to an attacker-controlled domain.
+     * </p>
+     *
+     * @param issuerUrl the normalized issuer URL
+     * @param jwksUri   the {@code jwks_uri} from discovery metadata
+     * @throws VerifyAccessTokenException if the hosts do not match
+     */
+    private void validateJwksUriHost(String issuerUrl, String jwksUri) throws VerifyAccessTokenException {
+        try {
+            String issuerHost = new URL(issuerUrl).getHost().toLowerCase(Locale.ROOT);
+            String jwksHost = new URL(jwksUri).getHost().toLowerCase(Locale.ROOT);
+            if (!issuerHost.equals(jwksHost)) {
+                throw new VerifyAccessTokenException("JWKS URI host does not match issuer host");
+            }
+        } catch (MalformedURLException e) {
+            throw new VerifyAccessTokenException("Invalid URL during JWKS URI host validation", e);
+        }
+    }
+
     /**
      * Normalizes a domain string into a full HTTPS URL with a trailing slash.
-     * Ensures consistent comparison (e.g., {@code "tenant.auth0.com"} becomes
+     * <p>
+     * Lowercases the scheme and host per RFC 3986 (scheme and host are
+     * case-insensitive). Ensures consistent comparison regardless of how the
+     * domain was configured (e.g., {@code "Tenant.Auth0.com"} becomes
      * {@code "https://tenant.auth0.com/"}).
+     * </p>
      *
      * @param domain the raw domain or URL string
      * @return the normalized URL, or {@code null} if input is {@code null}
@@ -354,9 +385,28 @@ private String normalizeToUrl(String domain) {
             return null;
 
         String url = domain.trim();
-        if (!url.toLowerCase().startsWith("http")) {
+        if (!url.toLowerCase(Locale.ROOT).startsWith("http")) {
             url = "https://" + url;
         }
-        return url.endsWith("/") ? url : url + "/";
+
+        try {
+            URL parsed = new URL(url);
+            StringBuilder normalized = new StringBuilder();
+            normalized.append(parsed.getProtocol().toLowerCase(Locale.ROOT));
+            normalized.append("://");
+            normalized.append(parsed.getHost().toLowerCase(Locale.ROOT));
+            int port = parsed.getPort();
+            if (port > 0 && port != parsed.getDefaultPort()) {
+                normalized.append(":").append(port);
+            }
+            String path = parsed.getPath();
+            normalized.append(path == null || path.isEmpty() ? "/" : path);
+            String result = normalized.toString();
+            return result.endsWith("/") ? result : result + "/";
+        } catch (MalformedURLException e) {
+            // Fallback: simple lowercase normalization
+            url = url.toLowerCase(Locale.ROOT);
+            return url.endsWith("/") ? url : url + "/";
+        }
     }
 }

auth0-api-java/src/main/java/com/auth0/OidcDiscoveryFetcher.java

@@ -11,6 +11,7 @@
 import org.apache.http.impl.client.HttpClients;
 import org.apache.http.util.EntityUtils;
 
+import java.io.Closeable;
 import java.io.IOException;
 
 /**
@@ -25,32 +26,44 @@
  * <p>
  * Thread-safe: delegates thread safety to the {@link AuthCache} implementation.
  * </p>
+ * <p>
+ * Implements {@link Closeable} to manage the lifecycle of the internal HTTP client.
+ * Only self-created HTTP clients are closed; externally-provided clients are left
+ * to the caller.
+ * </p>
  */
-class OidcDiscoveryFetcher {
+class OidcDiscoveryFetcher implements Closeable {
 
     static final String CACHE_PREFIX = "discovery:";
     private static final String WELL_KNOWN_PATH = ".well-known/openid-configuration";
     private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
 
     private final AuthCache<Object> cache;
     private final CloseableHttpClient httpClient;
+    private final boolean ownsHttpClient;
 
     /**
      * Creates a fetcher with the provided cache and the default HTTP client.
+     * The fetcher owns the HTTP client and will close it when {@link #close()} is called.
      *
      * @param cache the unified cache instance
      */
     OidcDiscoveryFetcher(AuthCache<Object> cache) {
-        this(cache, HttpClients.createDefault());
+        this(cache, HttpClients.createDefault(), true);
     }
 
     /**
      * Creates a fetcher with the provided cache and a custom HTTP client.
+     * The caller retains ownership of the HTTP client and is responsible for closing it.
      *
      * @param cache      the unified cache instance
      * @param httpClient the HTTP client to use for discovery requests
      */
     OidcDiscoveryFetcher(AuthCache<Object> cache, CloseableHttpClient httpClient) {
+        this(cache, httpClient, false);
+    }
+
+    private OidcDiscoveryFetcher(AuthCache<Object> cache, CloseableHttpClient httpClient, boolean ownsHttpClient) {
         if (cache == null) {
             throw new IllegalArgumentException("cache must not be null");
         }
@@ -59,6 +72,7 @@ class OidcDiscoveryFetcher {
         }
         this.cache = cache;
         this.httpClient = httpClient;
+        this.ownsHttpClient = ownsHttpClient;
     }
 
     /**
@@ -152,4 +166,15 @@ int cacheSize() {
     AuthCache<Object> getCache() {
         return cache;
     }
+
+    /**
+     * Closes the HTTP client if this fetcher owns it.
+     * Externally-provided HTTP clients are not closed — the caller manages their lifecycle.
+     */
+    @Override
+    public void close() throws IOException {
+        if (ownsHttpClient) {
+            httpClient.close();
+        }
+    }
 }

auth0-springboot-api/EXAMPLES.md

@@ -280,18 +280,164 @@ public class AdminController {
 }
 ```
 
+## Multiple Custom Domains (MCD)
+
+For APIs that accept tokens from multiple Auth0 custom domains (e.g., multi-tenant SaaS, domain migrations).
+
+### 1. Static Domain List
+
+Configure a fixed set of allowed issuer domains in `application.yml`:
+
+```yaml
+auth0:
+  audience: "https://api.example.com"
+  domains:
+    - "login.acme.com"
+    - "auth.partner.com"
+    - "dev.example.com"
+```
+
+Tokens whose `iss` claim matches any of these domains will be accepted. No code changes required.
+
+### 2. Dynamic Domain Resolver
+
+For scenarios where the allowed issuers depend on runtime context (tenant headers, database lookups, etc.), define a `DomainResolver` bean:
+
+```java
+import com.auth0.DomainResolver;
+import com.auth0.models.RequestContext;
+
+@Configuration
+public class McdConfig {
+
+    @Bean
+    public DomainResolver domainResolver(TenantService tenantService) {
+        return context -> {
+            // context.getHeaders()      — request headers (lowercase keys)
+            // context.getUrl()          — the API request URL
+            // context.getTokenIssuer()  — unverified iss claim (routing hint only)
+            String tenantId = context.getHeaders().get("x-tenant-id");
+            List<String> domains = tenantService.getDomainsForTenant(tenantId);
+            return domains;
+        };
+    }
+}
+```
+
+When a `DomainResolver` bean is present, it takes priority over the static `domains` list. The resolver receives a `RequestContext` with the request URL, headers, and the unverified `iss` claim from the token.
+
+### 3. Domain + Domains Coexistence (Auth for Agents)
+
+For Auth for Agents scenarios, `domain` and `domains` can coexist. The `domain` is used for Auth for Agents flows (token exchange, authorization), while `domains` is used for token validation:
+
+```yaml
+auth0:
+  domain: "primary-tenant.auth0.com"    # For Auth for Agents flows
+  audience: "https://api.example.com"
+  domains:                               # For token validation
+    - "primary-tenant.auth0.com"
+    - "tenant2.auth0.com"
+    - "tenant3.auth0.com"
+```
+
+When both are present, the SDK always uses `domains` for token verification.
+
+## Caching
+
+The SDK caches OIDC discovery metadata and JWKS providers in a unified cache. By default, it uses a thread-safe in-memory LRU cache.
+
+### Cache Configuration
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://api.example.com"
+  cache-max-entries: 100   # Max entries before LRU eviction (default: 100)
+  cache-ttl-seconds: 600   # TTL per entry in seconds (default: 600 = 10 minutes)
+```
+
+Both OIDC discovery and JWKS entries count against the `cache-max-entries` limit.
+
+### Custom Cache Implementation
+
+Replace the default in-memory cache with a distributed backend (Redis, Memcached, etc.) by implementing the `AuthCache` interface and registering it as a Spring bean:
+
+```java
+import com.auth0.AuthCache;
+
+public class RedisAuthCache implements AuthCache<Object> {
+
+    private final RedisTemplate<String, Object> redisTemplate;
+    private final Duration ttl;
+
+    public RedisAuthCache(RedisTemplate<String, Object> redisTemplate, Duration ttl) {
+        this.redisTemplate = redisTemplate;
+        this.ttl = ttl;
+    }
+
+    @Override
+    public Object get(String key) {
+        return redisTemplate.opsForValue().get(key);
+    }
+
+    @Override
+    public void put(String key, Object value) {
+        redisTemplate.opsForValue().set(key, value, ttl);
+    }
+
+    @Override
+    public void remove(String key) {
+        redisTemplate.delete(key);
+    }
+
+    @Override
+    public void clear() {
+        Set<String> keys = redisTemplate.keys("discovery:*");
+        if (keys != null) redisTemplate.delete(keys);
+        keys = redisTemplate.keys("jwks:*");
+        if (keys != null) redisTemplate.delete(keys);
+    }
+
+    @Override
+    public int size() {
+        return 0; // approximate
+    }
+}
+```
+
+Register it as a bean — the auto-configuration picks it up automatically:
+
+```java
+@Configuration
+public class CacheConfig {
+
+    @Bean
+    public AuthCache<Object> authCache(RedisTemplate<String, Object> redisTemplate) {
+        return new RedisAuthCache(redisTemplate, Duration.ofMinutes(10));
+    }
+}
+```
+
+When a custom `AuthCache` bean is present, the `cache-max-entries` and `cache-ttl-seconds` properties are ignored — your implementation controls its own eviction and TTL.
+
 ## Configuration Reference
 
 ### Complete Configuration Example
 
 ```yaml
 auth0:
-  # Required: Your Auth0 domain
+  # Required (unless domains or domainsResolver is set): Your Auth0 domain
   domain: "your-tenant.auth0.com"
 
   # Required: API identifier/audience
   audience: "https://api.example.com"
 
+  # Optional: Static list of allowed issuer domains (MCD)
+  # Mutually exclusive with domainsResolver bean
+  domains:
+    - "login.acme.com"
+    - "auth.partner.com"
+
   # Optional: DPoP mode (DISABLED, ALLOWED, REQUIRED)
   # Default: ALLOWED
   dpop-mode: ALLOWED
@@ -303,6 +449,14 @@ auth0:
   # Optional: DPoP proof time leeway in seconds
   # Default: 30 (30 seconds)
   dpop-iat-leeway-seconds: 30
+
+  # Optional: Max cache entries before LRU eviction
+  # Default: 100
+  cache-max-entries: 100
+
+  # Optional: Cache TTL in seconds
+  # Default: 600 (10 minutes)
+  cache-ttl-seconds: 600
 ```
 
 ### Environment Variables
@@ -312,9 +466,12 @@ You can also configure using environment variables:
 ```bash
 AUTH0_DOMAIN=your-tenant.auth0.com
 AUTH0_AUDIENCE=https://api.example.com
+AUTH0_DOMAINS=login.acme.com,auth.partner.com
 AUTH0_DPOPMODE=ALLOWED
 AUTH0_DPOPIATOFFSETSECONDS=300
 AUTH0_DPOPIATLEEWAYSSECONDS=30
+AUTH0_CACHEMAXENTRIES=100
+AUTH0_CACHETTLSECONDS=600
 ```
 
 > **Note:** Spring Boot environment variable binding removes dashes and is case-insensitive. Do not use underscores to separate words within a property name (e.g., use `AUTH0_DPOPMODE`, not `AUTH0_DPOP_MODE`).