SCANJLIB-309 Add sonar.scanner.httpExtraHeaders support for custom auth schemes (#285)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: henryju

its/it-tests/src/test/java/com/sonar/scanner/lib/it/tools/CommandExecutor.java

@@ -45,7 +45,7 @@
 
 public class CommandExecutor {
   private static final Logger LOG = LoggerFactory.getLogger(CommandExecutor.class);
-  private static final int TIMEOUT = 20_000;
+  private static final int TIMEOUT = 120_000;
   private Path file;
 
   private ByteArrayOutputStream logs;

lib/pom.xml

@@ -61,6 +61,10 @@
       <artifactId>bcprov-jdk18on</artifactId>
       <version>1.83</version>
     </dependency>
+    <dependency>
+      <groupId>de.siegmar</groupId>
+      <artifactId>fastcsv</artifactId>
+    </dependency>
 
     <!-- unit tests -->
     <dependency>

lib/src/main/java/org/sonarsource/scanner/lib/ScannerProperties.java

@@ -128,4 +128,12 @@ private ScannerProperties() {
    * Java options to be used by the scanner-engine.
    */
   public static final String SCANNER_JAVA_OPTS = "sonar.scanner.javaOpts";
+
+  /**
+   * Extra HTTP headers to add to every request sent by the scanner bootstrapper, in RFC 4180 CSV
+   * format: comma-separated {@code Name: Value} fields. Fields whose value contains a comma must
+   * be quoted, e.g. {@code X-Auth: token,"X-Link: <url1>, <url2>"}.
+   * The {@code User-Agent} header cannot be overridden via this property.
+   */
+  public static final String SONAR_SCANNER_HTTP_EXTRA_HEADERS = "sonar.scanner.httpExtraHeaders";
 }

lib/src/main/java/org/sonarsource/scanner/lib/internal/http/HttpConfig.java

@@ -19,13 +19,15 @@
  */
 package org.sonarsource.scanner.lib.internal.http;
 
+import de.siegmar.fastcsv.reader.CsvReader;
 import java.net.InetSocketAddress;
 import java.net.Proxy;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.time.Duration;
 import java.time.format.DateTimeParseException;
+import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
@@ -53,6 +55,7 @@
 import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_PROXY_PORT;
 import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_PROXY_USER;
 import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_RESPONSE_TIMEOUT;
+import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS;
 import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_SKIP_JVM_SSL_CONFIG;
 import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_SKIP_SYSTEM_TRUSTSTORE;
 import static org.sonarsource.scanner.lib.ScannerProperties.SONAR_SCANNER_SOCKET_TIMEOUT;
@@ -96,6 +99,9 @@ public class HttpConfig {
   private final String proxyPassword;
   private final String userAgent;
   private final boolean skipSystemTrustMaterial;
+  private final Map<String, String> extraHeaders;
+  private final boolean hasCustomAuthorization;
+  private final boolean hasCustomProxyAuthorization;
 
   public HttpConfig(Map<String, String> bootstrapProperties, Path sonarUserHome, System2 system) {
     this.webApiBaseUrl = StringUtils.removeEnd(bootstrapProperties.get(ScannerProperties.HOST_URL), "/");
@@ -117,6 +123,9 @@ public HttpConfig(Map<String, String> bootstrapProperties, Path sonarUserHome, S
     this.proxyUser = loadProxyUser(bootstrapProperties);
     this.proxyPassword = loadProxyPassword(bootstrapProperties);
     this.skipSystemTrustMaterial = Boolean.parseBoolean(defaultIfBlank(bootstrapProperties.get(SONAR_SCANNER_SKIP_SYSTEM_TRUSTSTORE), "false"));
+    this.extraHeaders = parseExtraHeaders(bootstrapProperties);
+    this.hasCustomAuthorization = extraHeaders.keySet().stream().anyMatch("authorization"::equalsIgnoreCase);
+    this.hasCustomProxyAuthorization = extraHeaders.keySet().stream().anyMatch("proxy-authorization"::equalsIgnoreCase);
   }
 
   @CheckForNull
@@ -300,4 +309,58 @@ public String getProxyPassword() {
   public boolean skipSystemTruststore() {
     return skipSystemTrustMaterial;
   }
+
+  public Map<String, String> getExtraHeaders() {
+    return extraHeaders;
+  }
+
+  public boolean hasCustomAuthorization() {
+    return hasCustomAuthorization;
+  }
+
+  public boolean hasCustomProxyAuthorization() {
+    return hasCustomProxyAuthorization;
+  }
+
+  private static Map<String, String> parseExtraHeaders(Map<String, String> bootstrapProperties) {
+    var rawValue = bootstrapProperties.get(SONAR_SCANNER_HTTP_EXTRA_HEADERS);
+    if (rawValue == null || rawValue.isBlank()) {
+      return Map.of();
+    }
+    var headers = new LinkedHashMap<String, String>();
+    try (var reader = CsvReader.builder().ofCsvRecord(rawValue)) {
+      for (var csvRecord : reader) {
+        for (var field : csvRecord.getFields()) {
+          var trimmed = field.trim();
+          if (!trimmed.isEmpty()) {
+            parseAndAddHeader(headers, trimmed);
+          }
+        }
+      }
+    } catch (IllegalArgumentException e) {
+      throw e;
+    } catch (Exception e) {
+      throw new IllegalArgumentException("Failed to parse '" + SONAR_SCANNER_HTTP_EXTRA_HEADERS + "': " + e.getMessage(), e);
+    }
+    return Map.copyOf(headers);
+  }
+
+  private static void parseAndAddHeader(Map<String, String> headers, String field) {
+    int colonIdx = field.indexOf(':');
+    if (colonIdx < 0) {
+      throw new IllegalArgumentException(
+        "Invalid HTTP header in '" + SONAR_SCANNER_HTTP_EXTRA_HEADERS + "': \"" + field + "\". Expected format: \"Name: Value\"");
+    }
+    var name = field.substring(0, colonIdx).trim();
+    if (name.isEmpty()) {
+      throw new IllegalArgumentException(
+        "Invalid HTTP header in '" + SONAR_SCANNER_HTTP_EXTRA_HEADERS + "': \"" + field + "\". Header name cannot be blank");
+    }
+    if (name.equalsIgnoreCase("User-Agent")) {
+      LOG.warn("The 'User-Agent' header cannot be overridden via '{}'. Ignoring.", SONAR_SCANNER_HTTP_EXTRA_HEADERS);
+      return;
+    }
+    var value = field.substring(colonIdx + 1).trim();
+    headers.put(name, value);
+  }
 }

lib/src/main/java/org/sonarsource/scanner/lib/internal/http/ScannerHttpClient.java

@@ -224,7 +224,11 @@ private HttpRequest prepareRequest(String url, @Nullable String acceptHeader, bo
       requestBuilder.header("Accept", acceptHeader);
     }
 
-    if (authentication) {
+    // Extra headers are sent on every request (authenticated or not), to support corporate
+    // proxies or SSO systems that require a specific header on all outbound traffic.
+    httpConfig.getExtraHeaders().forEach(requestBuilder::header);
+
+    if (authentication && !httpConfig.hasCustomAuthorization()) {
       if (httpConfig.getToken() != null) {
         requestBuilder.header("Authorization", "Bearer " + httpConfig.getToken());
       } else if (httpConfig.getLogin() != null) {
@@ -238,7 +242,7 @@ private HttpRequest prepareRequest(String url, @Nullable String acceptHeader, bo
     // Proxy-Authorization from the application request to CONNECT tunnel requests for HTTPS
     // targets, so sending it upfront avoids a round-trip 407 challenge and works reliably
     // across JDK versions.
-    if (httpConfig.getProxyUser() != null) {
+    if (!httpConfig.hasCustomProxyAuthorization() && httpConfig.getProxyUser() != null) {
       String proxyCredentials = httpConfig.getProxyUser() + ":" + (httpConfig.getProxyPassword() != null ? httpConfig.getProxyPassword() : "");
       String encodedProxyCredentials = Base64.getEncoder().encodeToString(proxyCredentials.getBytes(StandardCharsets.UTF_8));
       requestBuilder.header("Proxy-Authorization", "Basic " + encodedProxyCredentials);

lib/src/test/java/org/sonarsource/scanner/lib/internal/http/HttpConfigTest.java

@@ -28,10 +28,12 @@
 import java.util.HashMap;
 import java.util.Map;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 import org.junit.jupiter.api.io.TempDir;
 import org.slf4j.event.Level;
+import org.sonarsource.scanner.lib.ScannerProperties;
 import org.sonarsource.scanner.lib.internal.util.System2;
 import testutils.LogTester;
 
@@ -125,6 +127,96 @@ void should_skip_ssl_config_from_jvm_if_property_set() {
     assertThat(underTest.getSslConfig().getKeyStore()).isNull();
   }
 
+  @Nested
+  class ExtraHeaders {
+
+    @Test
+    void extraHeaders_are_empty_by_default() {
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders()).isEmpty();
+    }
+
+    @Test
+    void extraHeaders_single_header() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "X-Auth: mytoken");
+
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders()).containsOnly(Map.entry("X-Auth", "mytoken"));
+    }
+
+    @Test
+    void extraHeaders_multiple_headers() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "X-Auth: mytoken,X-Tenant-Id: company");
+
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders())
+        .containsOnly(Map.entry("X-Auth", "mytoken"), Map.entry("X-Tenant-Id", "company"));
+    }
+
+    @Test
+    void extraHeaders_trims_whitespace() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, " X-Auth : mytoken , X-Tenant-Id : company ");
+
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders())
+        .containsOnly(Map.entry("X-Auth", "mytoken"), Map.entry("X-Tenant-Id", "company"));
+    }
+
+    @Test
+    void extraHeaders_handles_comma_in_quoted_value() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "X-Auth: mytoken,\"X-Link: <url1>, <url2>\"");
+
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders())
+        .containsOnly(Map.entry("X-Auth", "mytoken"), Map.entry("X-Link", "<url1>, <url2>"));
+    }
+
+    @Test
+    void extraHeaders_warns_and_skips_user_agent() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "User-Agent: custom-agent");
+
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders()).isEmpty();
+      assertThat(logTester.logs(Level.WARN))
+        .contains("The 'User-Agent' header cannot be overridden via 'sonar.scanner.httpExtraHeaders'. Ignoring.");
+    }
+
+    @Test
+    void extraHeaders_throws_on_malformed_entry() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "no-colon-here");
+
+      assertThatThrownBy(() -> new HttpConfig(bootstrapProperties, sonarUserHome, system))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("sonar.scanner.httpExtraHeaders")
+        .hasMessageContaining("no-colon-here");
+    }
+
+    @Test
+    void extraHeaders_ignores_trailing_comma() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "X-Auth: mytoken,");
+
+      var underTest = new HttpConfig(bootstrapProperties, sonarUserHome, system);
+
+      assertThat(underTest.getExtraHeaders()).containsOnly(Map.entry("X-Auth", "mytoken"));
+    }
+
+    @Test
+    void extraHeaders_throws_on_blank_name() {
+      bootstrapProperties.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, ": value");
+
+      assertThatThrownBy(() -> new HttpConfig(bootstrapProperties, sonarUserHome, system))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("sonar.scanner.httpExtraHeaders")
+        .hasMessageContaining("Header name cannot be blank");
+    }
+  }
+
   @Test
   void should_set_ssl_config_from_jvm_system_properties(@TempDir Path tempDir) throws IOException {
     var jvmTruststore = tempDir.resolve("jvmTrust.p12");

lib/src/test/java/org/sonarsource/scanner/lib/internal/http/ScannerHttpClientTest.java

@@ -198,6 +198,74 @@ void downloadFromExternalUrl_shouldNotPassAuth(@TempDir Path tmpFolder) throws E
       .withoutHeader("Authorization"));
   }
 
+  @Test
+  void should_send_extra_headers_on_authenticated_requests() {
+    Map<String, String> props = new HashMap<>();
+    props.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "X-Auth: mytoken,X-Tenant-Id: company");
+    ScannerHttpClient connection = create(sonarqube.baseUrl(), props);
+
+    answer(HELLO_WORLD);
+    connection.callWebApi("/batch/index.txt");
+
+    sonarqube.verify(getRequestedFor(anyUrl())
+      .withHeader("X-Auth", equalTo("mytoken"))
+      .withHeader("X-Tenant-Id", equalTo("company")));
+  }
+
+  @Test
+  void should_also_send_extra_headers_on_external_url(@TempDir Path tmpFolder) {
+    var toFile = tmpFolder.resolve("index.txt");
+    Map<String, String> props = new HashMap<>();
+    props.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "X-Corp-Token: secret");
+    ScannerHttpClient underTest = create(sonarqube.baseUrl(), props);
+
+    answer(HELLO_WORLD);
+    underTest.downloadFromExternalUrl(sonarqube.baseUrl() + "/batch/index.txt", toFile);
+
+    sonarqube.verify(getRequestedFor(anyUrl())
+      .withHeader("X-Corp-Token", equalTo("secret")));
+  }
+
+  @Test
+  void should_use_extra_authorization_header_instead_of_token() {
+    Map<String, String> props = new HashMap<>();
+    props.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "Authorization: Bearer custom-scheme-token");
+    ScannerHttpClient connection = create(sonarqube.baseUrl(), props);
+
+    answer(HELLO_WORLD);
+    connection.callWebApi("/batch/index.txt");
+
+    sonarqube.verify(getRequestedFor(anyUrl())
+      .withHeader("Authorization", equalTo("Bearer custom-scheme-token")));
+  }
+
+  @Test
+  void should_not_duplicate_authorization_when_both_token_and_extra_auth_header_set() {
+    Map<String, String> props = new HashMap<>();
+    props.put("sonar.token", "some_token");
+    props.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "Authorization: Bearer custom-scheme-token");
+    ScannerHttpClient connection = create(sonarqube.baseUrl(), props);
+
+    answer(HELLO_WORLD);
+    connection.callWebApi("/batch/index.txt");
+
+    sonarqube.verify(getRequestedFor(anyUrl())
+      .withHeader("Authorization", equalTo("Bearer custom-scheme-token")));
+  }
+
+  @Test
+  void should_not_override_user_agent_via_extra_headers() {
+    Map<String, String> props = new HashMap<>();
+    props.put(ScannerProperties.SONAR_SCANNER_HTTP_EXTRA_HEADERS, "User-Agent: custom-agent");
+    ScannerHttpClient connection = create(sonarqube.baseUrl(), props);
+
+    answer(HELLO_WORLD);
+    connection.callWebApi("/batch/index.txt");
+
+    sonarqube.verify(getRequestedFor(anyUrl())
+      .withHeader("User-Agent", equalTo("user/agent")));
+  }
+
   @ParameterizedTest
   @ValueSource(ints = {301, 302, 303, 307, 308})
   void should_follow_redirects_and_preserve_authentication(int code) {

pom.xml

@@ -113,6 +113,11 @@
         <artifactId>commons-codec</artifactId>
         <version>1.21.0</version>
       </dependency>
+      <dependency>
+        <groupId>de.siegmar</groupId>
+        <artifactId>fastcsv</artifactId>
+        <version>3.7.0</version>
+      </dependency>
     </dependencies>
   </dependencyManagement>