feat: add TransportOptions for configuring TLS, proxy, and default headers

README.md

@@ -43,10 +43,14 @@ install dependencies.
 
 ### Installation
 
-Install the SDK by running one of the following commands:
-
-```bash
-composer require zitadel/client
+Add the SDK dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>io.github.zitadel</groupId>
+    <artifactId>client</artifactId>
+    <version>4.1.0</version>
+</dependency>
 ```
 
 ## Authentication Methods
@@ -193,6 +197,68 @@ Choose the authentication method that best suits your needs based on your
 environment and security requirements. For more details, please refer to the
 [Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
 
+## Advanced Configuration
+
+The SDK provides a `TransportOptions` builder that allows you to customise
+the underlying HTTP transport used for both OpenID discovery and API calls.
+
+### Disabling TLS Verification
+
+In development or testing environments with self-signed certificates, you can
+disable TLS verification entirely:
+
+```java
+TransportOptions options = new TransportOptions.Builder()
+    .insecure(true)
+    .build();
+
+Zitadel zitadel = Zitadel.withClientCredentials(
+    "https://your-instance.zitadel.cloud", "client-id", "client-secret", options);
+```
+
+### Using a Custom CA Certificate
+
+If your Zitadel instance uses a certificate signed by a private CA, you can
+provide the path to the CA certificate in PEM format:
+
+```java
+TransportOptions options = new TransportOptions.Builder()
+    .caCertPath("/path/to/ca.pem")
+    .build();
+
+Zitadel zitadel = Zitadel.withClientCredentials(
+    "https://your-instance.zitadel.cloud", "client-id", "client-secret", options);
+```
+
+### Custom Default Headers
+
+You can attach default headers to every outgoing request. This is useful for
+custom routing or tracing headers:
+
+```java
+TransportOptions options = new TransportOptions.Builder()
+    .defaultHeader("X-Custom-Header", "my-value")
+    .build();
+
+Zitadel zitadel = Zitadel.withClientCredentials(
+    "https://your-instance.zitadel.cloud", "client-id", "client-secret", options);
+```
+
+### Proxy Configuration
+
+If your environment requires routing traffic through an HTTP proxy, you can
+specify the proxy URL. To authenticate with the proxy, embed the credentials
+directly in the URL:
+
+```java
+TransportOptions options = new TransportOptions.Builder()
+    .proxyUrl("http://user:pass@proxy:8080")
+    .build();
+
+Zitadel zitadel = Zitadel.withClientCredentials(
+    "https://your-instance.zitadel.cloud", "client-id", "client-secret", options);
+```
+
 ## Design and Dependencies
 
 This SDK is designed to be lean and efficient, focusing on providing a

pom.xml

@@ -324,6 +324,7 @@
               <exclude>**/api/*.java</exclude>
               <exclude>**/model/*.java</exclude>
             </excludes>
+            <removeUnusedImports/>
             <googleJavaFormat/>
           </java>
         </configuration>

spotbugs.xml

@@ -14,4 +14,17 @@
     <Package name="~com\.zitadel\..*"/>
     <Bug pattern="THROWS_METHOD_THROWS_RUNTIMEEXCEPTION"/>
   </Match>
+  <!-- Constructors that perform I/O intentionally throw -->
+  <Match>
+    <Or>
+      <Class name="com.zitadel.ApiClient"/>
+      <Class name="com.zitadel.auth.OpenId"/>
+    </Or>
+    <Bug pattern="CT_CONSTRUCTOR_THROW"/>
+  </Match>
+  <!-- Builder field used by subclass builders via Zitadel factory -->
+  <Match>
+    <Class name="com.zitadel.auth.OAuthAuthenticator$OAuthAuthenticatorBuilder"/>
+    <Bug pattern="URF_UNREAD_PUBLIC_OR_PROTECTED_FIELD"/>
+  </Match>
 </FindBugsFilter>

src/main/java/com/zitadel/ApiClient.java

@@ -15,20 +15,27 @@
 import org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder;
 import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
 import org.apache.hc.client5.http.impl.classic.CloseableHttpResponse;
+import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
 import org.apache.hc.client5.http.impl.classic.HttpClients;
 import org.apache.hc.client5.http.protocol.HttpClientContext;
+import org.apache.hc.client5.http.ssl.NoopHostnameVerifier;
+import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactoryBuilder;
+import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder;
 import org.apache.hc.core5.http.*;
 import org.apache.hc.core5.http.io.entity.ByteArrayEntity;
 import org.apache.hc.core5.http.io.entity.EntityUtils;
 import org.apache.hc.core5.http.io.entity.FileEntity;
 import org.apache.hc.core5.http.io.entity.StringEntity;
 import org.apache.hc.core5.http.io.support.ClassicRequestBuilder;
+import org.apache.hc.core5.http.message.BasicHeader;
 import org.apache.hc.core5.http.message.BasicNameValuePair;
 import org.openapitools.jackson.nullable.JsonNullableModule;
 
 import javax.annotation.Nullable;
+import javax.net.ssl.SSLContext;
 import java.io.File;
 import java.io.IOException;
+import java.security.GeneralSecurityException;
 import java.lang.reflect.Type;
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
@@ -68,7 +75,7 @@
 
     public ApiClient(Authenticator authenticator, CloseableHttpClient httpClient) {
         objectMapper = new ObjectMapper();
         objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
         objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
         objectMapper.configure(DeserializationFeature.FAIL_ON_INVALID_SUBTYPE, false);
         objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
@@ -91,6 +98,55 @@
         this(authenticator, HttpClients.custom().setUserAgent(USER_AGENT).build());
     }
 
+    public ApiClient(Authenticator authenticator, TransportOptions transportOptions) {
+        this(authenticator, buildHttpClient(transportOptions != null ? transportOptions : TransportOptions.defaults()));
+    }
+
+    private static CloseableHttpClient buildHttpClient(TransportOptions transportOptions) {
+        try {
+            HttpClientBuilder builder = HttpClients.custom().setUserAgent(USER_AGENT);
+
+            SSLContext sslContext = transportOptions.buildSSLContext();
+            if (sslContext != null) {
+                SSLConnectionSocketFactoryBuilder sslSocketFactoryBuilder = SSLConnectionSocketFactoryBuilder.create()
+                    .setSslContext(sslContext);
+                if (transportOptions.isInsecure()) {
+                    sslSocketFactoryBuilder.setHostnameVerifier(NoopHostnameVerifier.INSTANCE);
+                }
+                builder.setConnectionManager(PoolingHttpClientConnectionManagerBuilder.create()
+                    .setSSLSocketFactory(sslSocketFactoryBuilder.build())
+                    .build());
+            }
+
+            List<Header> defaultHeaders = new ArrayList<>();
+
+            if (transportOptions.getProxyUrl() != null) {
+                java.net.URL proxyParsed = new java.net.URL(transportOptions.getProxyUrl());
+                String proxyScheme = proxyParsed.getProtocol();
+                String proxyHost = proxyParsed.getHost();
+                int proxyPort = proxyParsed.getPort() != -1 ? proxyParsed.getPort() : proxyParsed.getDefaultPort();
+                builder.setProxy(new HttpHost(proxyScheme, proxyHost, proxyPort));
+                if (proxyParsed.getUserInfo() != null) {
+                    String encoded = Base64.getEncoder()
+                        .encodeToString(proxyParsed.getUserInfo().getBytes(StandardCharsets.UTF_8));
+                    defaultHeaders.add(new BasicHeader("Proxy-Authorization", "Basic " + encoded));
+                }
+            }
+
+            for (Map.Entry<String, String> entry : transportOptions.getDefaultHeaders().entrySet()) {
+                defaultHeaders.add(new BasicHeader(entry.getKey(), entry.getValue()));
+            }
+
+            if (!defaultHeaders.isEmpty()) {
+                builder.setDefaultHeaders(defaultHeaders);
+            }
+
+            return builder.build();
+        } catch (IOException | GeneralSecurityException e) {
+            throw new RuntimeException("Failed to build HTTP client with transport options: " + e.getMessage(), e);
+        }
+    }
+
     public static DateFormat buildDefaultDateFormat() {
         return new RFC3339DateFormat();
     }
@@ -211,7 +267,7 @@
      * @param value The value of the parameter.
      * @return A list containing a single {@code Pair} object.
      */
     public List<Pair> parameterToPair(String name, Object value) {
         List<Pair> params = new ArrayList<>();
         if (name == null || name.isEmpty() || value == null || value instanceof Collection) {
             return params;
@@ -529,7 +585,7 @@
      * @return The full URL
      */
     @SuppressWarnings({"DuplicatedCode", "DuplicateExpressions"})
     private String buildUrl(
         String path,
         List<Pair> queryParams,
         @Nullable List<Pair> collectionQueryParams,