feat: add TransportOptions for configuring TLS, proxy, and default headers (#70)

Author: mridang

README.md

@@ -74,7 +74,7 @@ JSON file. This process creates a secure token.
 **Example:**
 
 ```php
-use \Zitadel\Client\Zitadel;
+use Zitadel\Client\Zitadel;
 
 $zitadel = Zitadel::withPrivateKey("https://example.us1.zitadel.cloud", "path/to/jwt-key.json");
 
@@ -93,6 +93,7 @@ try {
     echo "User created: " . print_r($response, true);
 } catch (ApiException $e) {
     echo "Error: " . $e->getMessage();
+}
 ```
 
 #### 2. Client Credentials Grant
@@ -116,9 +117,8 @@ which is then used to authenticate.
 ```php
 use Zitadel\Client\Zitadel;
 use Zitadel\Client\Model\UserServiceAddHumanUserRequest;
-use \Zitadel\Client\Model\UserServiceAddHumanUserRequest;
-use \Zitadel\Client\Model\UserServiceSetHumanProfile;
-use \Zitadel\Client\Model\UserServiceSetHumanEmail;
+use Zitadel\Client\Model\UserServiceSetHumanProfile;
+use Zitadel\Client\Model\UserServiceSetHumanEmail;
 
 $zitadel = Zitadel::withClientCredentials("https://example.us1.zitadel.cloud", "id", "secret");
 
@@ -159,12 +159,10 @@ authenticate without exchanging credentials every time.
 **Example:**
 
 ```php
-use \Zitadel\Client\Zitadel;
 use Zitadel\Client\Zitadel;
 use Zitadel\Client\Model\UserServiceAddHumanUserRequest;
-use \Zitadel\Client\Model\UserServiceAddHumanUserRequest;
-use \Zitadel\Client\Model\UserServiceSetHumanProfile;
-use \Zitadel\Client\Model\UserServiceSetHumanEmail;
+use Zitadel\Client\Model\UserServiceSetHumanProfile;
+use Zitadel\Client\Model\UserServiceSetHumanEmail;
 
 $zitadel = Zitadel::withAccessToken("https://example.us1.zitadel.cloud", "token");
 
@@ -194,6 +192,90 @@ 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` object 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:
+
+```php
+use Zitadel\Client\Zitadel;
+use Zitadel\Client\TransportOptions;
+
+$options = new TransportOptions(insecure: true);
+
+$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:
+
+```php
+use Zitadel\Client\Zitadel;
+use Zitadel\Client\TransportOptions;
+
+$options = new TransportOptions(caCertPath: '/path/to/ca.pem');
+
+$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:
+
+```php
+use Zitadel\Client\Zitadel;
+use Zitadel\Client\TransportOptions;
+
+$options = new TransportOptions(
+    defaultHeaders: ['X-Custom-Header' => 'my-value'],
+);
+
+$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:
+
+```php
+use Zitadel\Client\Zitadel;
+use Zitadel\Client\TransportOptions;
+
+$options = new TransportOptions(proxyUrl: 'http://user:pass@proxy:8080');
+
+$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

composer.json

@@ -27,14 +27,14 @@
         "guzzlehttp/psr7": "^1.7 || ^2.0",
         "firebase/php-jwt": "^7.0.0",
         "league/oauth2-client": "^2.8",
-        "league/uri": "^7.5"
+        "league/uri": "^7.5",
+        "ext-openssl": "*"
     },
     "require-dev": {
         "phpunit/phpunit": "^12.0",
         "friendsofphp/php-cs-fixer": "^3.75",
         "haydenpierce/class-finder": "^0.5.3",
         "testcontainers/testcontainers": "^1.0",
-        "ext-openssl": "*",
         "ext-dom": "*",
         "vlucas/phpdotenv": "^5.6",
         "rector/rector": "^2.0",

composer.lock

@@ -3,7 +3,9 @@
 namespace Zitadel\Client\Auth;
 
 use Exception;
+use GuzzleHttp\Client;
 use League\OAuth2\Client\Provider\GenericProvider;
+use Zitadel\Client\TransportOptions;
 
 /**
  * OAuth2 Client Credentials Authenticator.
@@ -21,20 +23,27 @@ class ClientCredentialsAuthenticator extends OAuthAuthenticator
      * @param string $clientId The OAuth2 client identifier.
      * @param string $clientSecret The OAuth2 client secret.
      * @param string $scope The scope for the token request.
+     * @param TransportOptions|null $transportOptions Optional transport options for TLS, proxy, and headers.
      */
     public function __construct(
         OpenId $hostName,
         string $clientId,
         string $clientSecret,
-        string $scope = 'openid urn:zitadel:iam:org:project:id:zitadel:aud'
+        string $scope = 'openid urn:zitadel:iam:org:project:id:zitadel:aud',
+        ?TransportOptions $transportOptions = null
     ) {
+        $transportOptions ??= TransportOptions::defaults();
+
+        $guzzleOpts = $transportOptions->toGuzzleOptions();
+        $collaborators = !empty($guzzleOpts) ? ['httpClient' => new Client($guzzleOpts)] : [];
+
         parent::__construct($hostName, $clientId, $scope, new GenericProvider([
             'clientId' => $clientId,
             'clientSecret' => $clientSecret,
             'urlAccessToken' => $hostName->getTokenEndpoint()->toString(),
             'urlAuthorize' => $hostName->getAuthorizationEndpoint()->toString(),
             'urlResourceOwnerDetails' => $hostName->getUserinfoEndpoint()->toString(),
-        ]));
+        ], $collaborators), $transportOptions);
     }
 
     /**
@@ -43,12 +52,17 @@ public function __construct(
      * @param string $host The base URL for API endpoints.
      * @param string $clientId The OAuth2 client identifier.
      * @param string $clientSecret The OAuth2 client secret.
+     * @param TransportOptions|null $transportOptions Optional transport options for TLS, proxy, and headers.
      * @return ClientCredentialsAuthenticatorBuilder A new builder instance.
      * @throws Exception
      */
-    public static function builder(string $host, string $clientId, string $clientSecret): ClientCredentialsAuthenticatorBuilder
-    {
-        return new ClientCredentialsAuthenticatorBuilder($host, $clientId, $clientSecret);
+    public static function builder(
+        string $host,
+        string $clientId,
+        string $clientSecret,
+        ?TransportOptions $transportOptions = null,
+    ): ClientCredentialsAuthenticatorBuilder {
+        return new ClientCredentialsAuthenticatorBuilder($host, $clientId, $clientSecret, $transportOptions);
     }
 
     protected function getGrantType(): string

lib/Auth/ClientCredentialsAuthenticator.php

@@ -3,6 +3,7 @@
 namespace Zitadel\Client\Auth;
 
 use Exception;
+use Zitadel\Client\TransportOptions;
 
 /**
  * Builder for ClientCredentialsAuthenticator.
@@ -18,11 +19,16 @@ final class ClientCredentialsAuthenticatorBuilder extends OAuthAuthenticatorBuil
      * @param string $host The base URL for API endpoints.
      * @param string $clientId The OAuth2 client identifier.
      * @param string $clientSecret The OAuth2 client secret.
+     * @param TransportOptions|null $transportOptions Optional transport options for TLS, proxy, and headers.
      * @throws Exception
      */
-    public function __construct(string $host, private readonly string $clientId, private readonly string $clientSecret)
-    {
-        parent::__construct($host);
+    public function __construct(
+        string $host,
+        private readonly string $clientId,
+        private readonly string $clientSecret,
+        ?TransportOptions $transportOptions = null,
+    ) {
+        parent::__construct($host, $transportOptions);
     }
 
     /**
@@ -36,7 +42,8 @@ public function build(): ClientCredentialsAuthenticator
             $this->hostName,
             $this->clientId,
             $this->clientSecret,
-            $this->authScopes
+            $this->authScopes,
+            $this->transportOptions
         );
     }
 }

lib/Auth/ClientCredentialsAuthenticatorBuilder.php

@@ -6,6 +6,7 @@
 use League\OAuth2\Client\Provider\GenericProvider;
 use League\OAuth2\Client\Token\AccessTokenInterface;
 use Throwable;
+use Zitadel\Client\TransportOptions;
 use Zitadel\Client\ZitadelException;
 
 /**
@@ -28,6 +29,12 @@ abstract class OAuthAuthenticator extends Authenticator
      * @var AccessTokenInterface|null
      */
     protected ?AccessTokenInterface $token;
+    /**
+     * Transport options for HTTP connections.
+     *
+     * @var TransportOptions
+     */
+    protected TransportOptions $transportOptions;
 
     /**
      * OAuthAuthenticator constructor.
@@ -36,18 +43,20 @@ abstract class OAuthAuthenticator extends Authenticator
      * @param string $clientId The OAuth2 client identifier.
      * @param string $scope The scope for the token request.
      * @param GenericProvider $provider
+     * @param TransportOptions|null $transportOptions Optional transport options for TLS, proxy, and headers.
      */
     public function __construct(OpenId           $openId, /**
      * The OAuth2 client identifier.
      */
         protected string $clientId, /**
          * The scope for the token request.
          */
-        protected string $scope, protected GenericProvider $provider)
+        protected string $scope, protected GenericProvider $provider, ?TransportOptions $transportOptions = null)
     {
         parent::__construct($openId->getHostEndpoint()->toString());
         $this->token = null;
         $this->openId = $openId;
+        $this->transportOptions = $transportOptions ?? TransportOptions::defaults();
     }
 
     /**

lib/Auth/OAuthAuthenticator.php

@@ -3,6 +3,7 @@
 namespace Zitadel\Client\Auth;
 
 use Exception;
+use Zitadel\Client\TransportOptions;
 
 /**
  * Base builder for OAuth authenticators.
@@ -14,16 +15,21 @@ abstract class OAuthAuthenticatorBuilder
 {
     protected OpenId $hostName;
     protected string $authScopes = 'openid urn:zitadel:iam:org:project:id:zitadel:aud';
+    protected TransportOptions $transportOptions;
 
     /**
      * Constructs the builder with the required host.
      *
      * @param string $hostName
+     * @param TransportOptions|null $transportOptions Optional transport options for TLS, proxy, and headers.
      * @throws Exception
      */
-    public function __construct(string $hostName)
-    {
-        $this->hostName = new OpenId($hostName);
+    public function __construct(
+        string $hostName,
+        ?TransportOptions $transportOptions = null,
+    ) {
+        $this->transportOptions = $transportOptions ?? TransportOptions::defaults();
+        $this->hostName = new OpenId($hostName, $this->transportOptions);
     }
 
     /**