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

Author: mridang

.releaserc.json

@@ -56,7 +56,7 @@
         ]
       }
     ],
-    "semantic-release-rubygem",
+    "@webhippie/semantic-release-rubygem",
     [
       "@semantic-release/git",
       {

README.md

@@ -194,22 +194,99 @@ environment and security requirements. For more details, please refer to the
 ### Debugging
 
 The SDK supports debug logging, which can be enabled for troubleshooting
-and debugging purposes. You can enable debug logging by setting the `debug`
-flag to `true` when initializing the `Zitadel` client, like this:
+and debugging purposes. You can enable debug logging by setting `debugging`
+to `true` via the configuration block when initializing the `Zitadel` client:
 
 ```ruby
-zitadel = zitadel.Zitadel("your-zitadel-base-url", 'your-valid-token', lambda config: config.debug = True)
+zitadel = Zitadel::Client::Zitadel.with_access_token(
+  'your-zitadel-base-url',
+  'your-valid-token'
+) do |config|
+  config.debugging = true
+end
 ```
 
 When enabled, the SDK will log additional information, such as HTTP request
 and response details, which can be useful for identifying issues in the
 integration or troubleshooting unexpected behavior.
 
+## 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:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(insecure: true)
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: 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:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(ca_cert_path: '/path/to/ca.pem')
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: options
+)
+```
+
+### Custom Default Headers
+
+You can attach default headers to every outgoing request. This is useful for
+custom routing or tracing headers:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(
+  default_headers: { 'X-Custom-Header' => 'my-value' }
+)
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: 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:
+
+```ruby
+options = Zitadel::Client::TransportOptions.new(proxy_url: 'http://user:pass@proxy:8080')
+
+zitadel = Zitadel::Client::Zitadel.with_client_credentials(
+  'https://your-instance.zitadel.cloud',
+  'client-id',
+  'client-secret',
+  transport_options: options
+)
+```
+
 ## Design and Dependencies
 
 This SDK is designed to be lean and efficient, focusing on providing a
 streamlined way to interact with the Zitadel API. It relies on the commonly used
-urllib3 HTTP transport for making requests, which ensures that
+Typhoeus HTTP library for making requests, which ensures that
 the SDK integrates well with other libraries and provides flexibility
 in terms of request handling and error management.
 

lib/zitadel/client/api_client.rb

@@ -48,7 +48,7 @@ def initialize(config = Configuration.new)
         @default_headers = {
           'Content-Type' => 'application/json',
           'User-Agent' => config.user_agent
-        }
+        }.merge(config.default_headers || {})
       end
 
       # noinspection RubyClassVariableUsageInspection,RbsMissingTypeSignature
@@ -114,6 +114,9 @@ def build_request(http_method, path, opts = {})
         # set custom cert, if provided
         req_opts[:cainfo] = @config.ssl_ca_cert if @config.ssl_ca_cert
 
+        # set proxy, if provided
+        req_opts[:proxy] = @config.proxy_url if @config.proxy_url
+
         if %i[post patch put delete].include?(http_method)
           req_body = build_request_body(header_params, form_params, opts[:body])
           req_opts.update body: req_body

lib/zitadel/client/auth/authenticator.rb

@@ -56,9 +56,12 @@ class OAuthAuthenticatorBuilder
         # Initializes the OAuthAuthenticatorBuilder with a given host.
         #
         # @param host [String] the base URL for the OAuth provider.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         #
-        def initialize(host)
-          @open_id = OpenId.new(host)
+        def initialize(host, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
+          @transport_options = transport_options
+          @open_id = OpenId.new(host, transport_options: transport_options)
           @auth_scopes = Set.new(%w[openid urn:zitadel:iam:org:project:id:zitadel:aud])
         end
 

lib/zitadel/client/auth/client_credentials_authenticator.rb

@@ -11,22 +11,30 @@ class ClientCredentialsAuthenticator < Auth::OAuthAuthenticator
         # @param client_id [String] The OAuth client identifier.
         # @param client_secret [String] The OAuth client secret.
         # @param auth_scopes [Set<String>] The scope(s) for the token request.
-        def initialize(open_id, client_id, client_secret, auth_scopes)
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        def initialize(open_id, client_id, client_secret, auth_scopes, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
+
+          conn_opts = transport_options.to_connection_opts
+
           # noinspection RubyArgCount
           super(open_id, auth_scopes, OAuth2::Client.new(client_id, client_secret, {
                                                            site: open_id.host_endpoint,
-                                                           token_url: open_id.token_endpoint
-                                                         }))
+                                                           token_url: open_id.token_endpoint,
+                                                           connection_opts: conn_opts
+                                                         }), transport_options: transport_options)
         end
 
         # Returns a new builder for constructing a ClientCredentialsAuthenticator.
         #
         # @param host [String] The OAuth provider's base URL.
         # @param client_id [String] The OAuth client identifier.
         # @param client_secret [String] The OAuth client secret.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @return [ClientCredentialsAuthenticatorBuilder] A builder instance.
-        def self.builder(host, client_id, client_secret)
-          ClientCredentialsAuthenticatorBuilder.new(host, client_id, client_secret)
+        def self.builder(host, client_id, client_secret, transport_options: nil)
+          ClientCredentialsAuthenticatorBuilder.new(host, client_id, client_secret,
+                                                    transport_options: transport_options)
         end
 
         protected
@@ -45,9 +53,10 @@ class ClientCredentialsAuthenticatorBuilder < OAuthAuthenticatorBuilder
           # @param host [String] The OAuth provider's base URL.
           # @param client_id [String] The OAuth client identifier.
           # @param client_secret [String] The OAuth client secret.
-          def initialize(host, client_id, client_secret)
+          # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+          def initialize(host, client_id, client_secret, transport_options: nil)
             # noinspection RubyArgCount
-            super(host)
+            super(host, transport_options: transport_options)
             @client_id = client_id
             @client_secret = client_secret
           end
@@ -56,7 +65,8 @@ def initialize(host, client_id, client_secret)
           #
           # @return [ClientCredentialsAuthenticator] A configured instance.
           def build
-            ClientCredentialsAuthenticator.new(open_id, @client_id, @client_secret, auth_scopes)
+            ClientCredentialsAuthenticator.new(open_id, @client_id, @client_secret, auth_scopes,
+                                               transport_options: @transport_options)
           end
         end
       end

lib/zitadel/client/auth/o_auth_authenticator.rb

@@ -25,11 +25,14 @@ class OAuthAuthenticator < Authenticator
         # Constructs an OAuthAuthenticator.
         #
         # @param open_id [OpenId] An object that must implement `get_host_endpoint` and `get_token_endpoint`.
-        # @param auth_session [OAuth2Session] The OAuth2Session instance used for token requests.
+        # @param auth_scopes [Set<String>] The scope(s) for the token request.
+        # @param auth_session [OAuth2::Client] The OAuth2 client instance used for token requests.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         #
-        def initialize(open_id, auth_scopes, auth_session)
+        def initialize(open_id, auth_scopes, auth_session, transport_options: nil)
           super(open_id.host_endpoint)
           @open_id = open_id
+          @transport_options = transport_options || TransportOptions.defaults
           @token = nil
           @auth_session = auth_session
           @auth_scopes = auth_scopes.to_a.join(' ')

lib/zitadel/client/auth/open_id.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'uri'
 require 'net/http'
+require 'openssl'
 
 module Zitadel
   module Client
@@ -20,16 +21,38 @@ class OpenId
         # Initializes a new OpenId instance.
         #
         # @param hostname [String] the hostname for the OpenID provider.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @raise [RuntimeError] if the OpenID configuration cannot be fetched or the token_endpoint is missing.
         #
         # noinspection HttpUrlsUsage
-        def initialize(hostname)
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def initialize(hostname, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
           hostname = "https://#{hostname}" unless hostname.start_with?('http://', 'https://')
           @host_endpoint = hostname
           well_known_url = self.class.build_well_known_url(hostname)
 
           uri = URI.parse(well_known_url)
-          response = Net::HTTP.get_response(uri)
+          http = if transport_options.proxy_url
+                   proxy_uri = URI.parse(transport_options.proxy_url)
+                   Net::HTTP.new(uri.host.to_s, uri.port, proxy_uri.host, proxy_uri.port,
+                                 proxy_uri.user, proxy_uri.password)
+                 else
+                   Net::HTTP.new(uri.host.to_s, uri.port)
+                 end
+          http.use_ssl = (uri.scheme == 'https')
+          if transport_options.insecure
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          elsif transport_options.ca_cert_path
+            store = OpenSSL::X509::Store.new
+            store.set_default_paths
+            store.add_file(transport_options.ca_cert_path)
+            http.cert_store = store
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          end
+          request = Net::HTTP::Get.new(uri)
+          transport_options.default_headers.each { |k, v| request[k] = v }
+          response = http.request(request)
           raise "Failed to fetch OpenID configuration: HTTP #{response.code}" unless response.code.to_i == 200
 
           config = JSON.parse(response.body)
@@ -38,6 +61,7 @@ def initialize(hostname)
 
           @token_endpoint = token_endpoint
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ##
         # Builds the well-known OpenID configuration URL for the given hostname.

lib/zitadel/client/auth/web_token_authenticator.rb

@@ -25,14 +25,20 @@ class WebTokenAuthenticator < Auth::OAuthAuthenticator
         # @param jwt_lifetime [Integer] Lifetime of the JWT in seconds (default 3600 seconds).
         # @param jwt_algorithm [String] The JWT signing algorithm (default "RS256").
         # @param key_id [String, nil] Optional key identifier for the JWT header (default: nil).
-        # rubocop:disable Metrics/ParameterLists,Metrics/MethodLength
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+        # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
         def initialize(open_id, auth_scopes, jwt_issuer, jwt_subject, jwt_audience, private_key,
-                       jwt_lifetime: 3600, jwt_algorithm: 'RS256', key_id: nil)
+                       jwt_lifetime: 3600, jwt_algorithm: 'RS256', key_id: nil, transport_options: nil)
+          transport_options ||= TransportOptions.defaults
+
+          conn_opts = transport_options.to_connection_opts
+
           # noinspection RubyArgCount,RubyMismatchedArgumentType
           super(open_id, auth_scopes, OAuth2::Client.new('zitadel', 'zitadel', {
                                                            site: open_id.host_endpoint,
-                                                           token_url: open_id.token_endpoint
-                                                         }))
+                                                           token_url: open_id.token_endpoint,
+                                                           connection_opts: conn_opts
+                                                         }), transport_options: transport_options)
           @jwt_issuer = jwt_issuer
           @jwt_subject = jwt_subject
           @jwt_audience = jwt_audience
@@ -47,7 +53,7 @@ def initialize(open_id, auth_scopes, jwt_issuer, jwt_subject, jwt_audience, priv
                          end
         end
 
-        # rubocop:enable Metrics/ParameterLists,Metrics/MethodLength
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
         # Creates a WebTokenAuthenticator instance from a JSON configuration file.
         #
@@ -62,9 +68,11 @@ def initialize(open_id, auth_scopes, jwt_issuer, jwt_subject, jwt_audience, priv
         #
         # @param host [String] Base URL for the API endpoints.
         # @param json_path [String] File path to the JSON configuration file.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @return [WebTokenAuthenticator] A new instance of WebTokenAuthenticator.
         # @raise [RuntimeError] If the file cannot be read, the JSON is invalid, or required keys are missing.
-        def self.from_json(host, json_path)
+        # rubocop:disable Metrics/MethodLength
+        def self.from_json(host, json_path, transport_options: nil)
           config = JSON.parse(File.read(json_path))
         rescue Errno::ENOENT => e
           raise "Unable to read JSON file at #{json_path}: #{e.message}"
@@ -76,17 +84,21 @@ def self.from_json(host, json_path)
           user_id, private_key, key_id = config.values_at('userId', 'key', 'keyId')
           raise "Missing required keys 'userId', 'keyId' or 'key'" unless user_id && key_id && private_key
 
-          WebTokenAuthenticator.builder(host, user_id, private_key).key_identifier(key_id).build
+          WebTokenAuthenticator.builder(host, user_id, private_key, transport_options: transport_options)
+                               .key_identifier(key_id).build
         end
+        # rubocop:enable Metrics/MethodLength
 
         # Returns a builder for constructing a WebTokenAuthenticator.
         #
         # @param host [String] The base URL for the OAuth provider.
         # @param user_id [String] The user identifier (used as both the issuer and subject).
         # @param private_key [String] The private key used to sign the JWT.
+        # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
         # @return [WebTokenAuthenticatorBuilder] A builder instance.
-        def self.builder(host, user_id, private_key)
-          WebTokenAuthenticatorBuilder.new(host, user_id, user_id, host, private_key)
+        def self.builder(host, user_id, private_key, transport_options: nil)
+          WebTokenAuthenticatorBuilder.new(host, user_id, user_id, host, private_key,
+                                           transport_options: transport_options)
         end
 
         protected
@@ -130,15 +142,18 @@ class WebTokenAuthenticatorBuilder < OAuthAuthenticatorBuilder
           # @param jwt_subject [String] The subject claim for the JWT.
           # @param jwt_audience [String] The audience claim for the JWT.
           # @param private_key [String] The PEM-formatted private key used for signing the JWT.
-          def initialize(host, jwt_issuer, jwt_subject, jwt_audience, private_key)
+          # @param transport_options [TransportOptions, nil] Optional transport options for TLS, proxy, and headers.
+          # rubocop:disable Metrics/ParameterLists
+          def initialize(host, jwt_issuer, jwt_subject, jwt_audience, private_key, transport_options: nil)
             # noinspection RubyArgCount
-            super(host)
+            super(host, transport_options: transport_options)
             @jwt_issuer = jwt_issuer
             @jwt_subject = jwt_subject
             @jwt_audience = jwt_audience
             @private_key = private_key
             @jwt_lifetime = 3600
           end
+          # rubocop:enable Metrics/ParameterLists
 
           # Sets the JWT token lifetime in seconds.
           #
@@ -159,7 +174,8 @@ def key_identifier(key_id)
           # @return [WebTokenAuthenticator] A configured instance.
           def build
             WebTokenAuthenticator.new(open_id, auth_scopes, @jwt_issuer, @jwt_subject, @jwt_audience,
-                                      @private_key, jwt_lifetime: @jwt_lifetime, key_id: @key_id)
+                                      @private_key, jwt_lifetime: @jwt_lifetime, key_id: @key_id,
+                                                    transport_options: @transport_options)
           end
         end
       end