zitadel-client 1.4.2 → 1.5.0

data/lib/zitadel/client/auth/authenticator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Zitadel
+  module Client
+    module Auth
+      ##
+      # Abstract base class for authenticators.
+      #
+      # This class defines the basic structure for any authenticator by requiring the implementation
+      # of a method to retrieve authentication headers, and provides a way to store and retrieve the host.
+      #
+      class Authenticator
+        protected
+
+        attr_reader :host
+
+        ##
+        # Initializes the Authenticator with the specified host.
+        #
+        # @param host [String] the base URL or endpoint for the service.
+        #
+        def initialize(host)
+          @host = host
+        end
+
+        ##
+        # Retrieves the authentication headers to be sent with requests.
+        #
+        # Subclasses must override this method to return the appropriate headers.
+        #
+        # @raise [NotImplementedError] Always raised to require implementation in a subclass.
+        #
+        # @return [Hash{String => String}]
+        #
+        def auth_headers
+          # :nocov:
+          raise NotImplementedError,
+                "#{self.class}#get_auth_headers is an abstract method. Please override it in a subclass."
+          # :nocov:
+        end
+      end
+
+      ##
+      # Abstract builder class for constructing OAuth authenticator instances.
+      #
+      # This builder provides common configuration options such as the OpenId instance and authentication scopes.
+      #
+      class OAuthAuthenticatorBuilder
+        protected
+
+        attr_reader :open_id, :auth_scopes
+
+        ##
+        # Initializes the OAuthAuthenticatorBuilder with a given host.
+        #
+        # @param host [String] the base URL for the OAuth provider.
+        #
+        def initialize(host)
+          @open_id = OpenId.new(host)
+          @auth_scopes = Set.new(%w[openid urn:zitadel:iam:org:project:id:zitadel:aud])
+        end
+
+        public
+
+        ##
+        # Sets the authentication scopes for the OAuth authenticator.
+        #
+        # @param scopes [Array<String>] a variable number of scope strings.
+        # @return [self] the builder instance to allow for method chaining.
+        #
+        def scopes(*scopes)
+          @auth_scopes = Set.new(scopes)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/zitadel/client/auth/client_credentials_authenticator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Zitadel
+  module Client
+    module Auth
+      # ClientCredentialsAuthenticator implements the client credentials flow.
+      class ClientCredentialsAuthenticator < Auth::OAuthAuthenticator
+        # Constructs a ClientCredentialsAuthenticator using client credentials flow.
+        #
+        # @param open_id [OpenId] The OpenId instance with OAuth endpoint info.
+        # @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)
+          # 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
+                                                         }))
+        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.
+        # @return [ClientCredentialsAuthenticatorBuilder] A builder instance.
+        def self.builder(host, client_id, client_secret)
+          ClientCredentialsAuthenticatorBuilder.new(host, client_id, client_secret)
+        end
+
+        protected
+
+        # Overrides the base get_grant to return client credentials grant parameters.
+
+        # @return [OAuth2::AccessToken] A hash containing the grant type.
+        def get_grant(client, auth_scopes)
+          client.client_credentials.get_token({ scope: auth_scopes })
+        end
+
+        # Builder class for ClientCredentialsAuthenticator.
+        class ClientCredentialsAuthenticatorBuilder < OAuthAuthenticatorBuilder
+          # Initializes the builder with host, client ID, and client secret.
+          #
+          # @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)
+            # noinspection RubyArgCount
+            super(host)
+            @client_id = client_id
+            @client_secret = client_secret
+          end
+
+          # Constructs and returns a ClientCredentialsAuthenticator using the configured parameters.
+          #
+          # @return [ClientCredentialsAuthenticator] A configured instance.
+          def build
+            ClientCredentialsAuthenticator.new(open_id, @client_id, @client_secret, auth_scopes)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zitadel/client/auth/no_auth_authenticator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Zitadel
+  module Client
+    module Auth
+      ##
+      # A simple authenticator that performs no authentication.
+      #
+      # This authenticator is useful for cases where no token or credentials are required.
+      # It simply returns an empty dictionary for authentication headers.
+      #
+      class NoAuthAuthenticator < Authenticator
+        ##
+        # Initializes the NoAuthAuthenticator with a default host.
+        #
+        # @param host [String] the base URL for the service. Defaults to "http://localhost".
+        #
+        def initialize(host = 'http://localhost')
+          super
+        end
+
+        protected
+
+        ##
+        # Returns an empty dictionary since no authentication is performed.
+        #
+        # @return [Hash{String => String}] an empty hash.
+        #
+        def auth_headers
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/zitadel/client/auth/o_auth_authenticator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'oauth2'
+
+OAuth2.configure do |config|
+  # noinspection RubyResolve
+  config.silence_extra_tokens_warning = true
+end
+
+module Zitadel
+  module Client
+    module Auth
+      ##
+      # Base class for OAuth-based authentication using an OAuth2 client.
+      #
+      # Attributes:
+      #   open_id: An object providing OAuth endpoint information.
+      #   auth_session: An OAuth2Session instance used for fetching tokens.
+      #
+      class OAuthAuthenticator < Authenticator
+        protected
+
+        ##
+        # 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.
+        #
+        def initialize(open_id, auth_scopes, auth_session)
+          super(open_id.host_endpoint)
+          @open_id = open_id
+          @token = nil
+          @auth_session = auth_session
+          @auth_scopes = auth_scopes.to_a.join(' ')
+        end
+
+        ##
+        # Returns the current access token, refreshing it if necessary.
+        #
+        # @return [String] The current access token.
+        #
+        def auth_token
+          token = @token
+          if token.nil? || token.expired?
+            refresh_token
+            token = @token
+          end
+
+          raise 'Token is nil after refresh' if token.nil?
+
+          token.token
+        end
+
+        ##
+        # Retrieves authentication headers.
+        #
+        # @return [Hash{String => String}] A hash containing the 'Authorization' header.
+        #
+        def auth_headers
+          { 'Authorization' => "Bearer #{auth_token}" }
+        end
+
+        ##
+        # Builds and returns a hash of grant parameters required for the token request.
+        #
+        # The base class will invoke this method by passing its OAuth2 client.
+        # The subclass implementation should return the result of either:
+        #   client.client_credentials.get_token(scope: scopes)
+        # or
+        #   client.assertion.get_token(claims)
+        #
+        # @param auth_client [OAuth2::Client] The OAuth2 client instance.
+        # @param [String] auth_scopes
+        # @return [OAuth2::AccessToken] A hash of parameters used to fetch a token.
+        #
+        def get_grant(auth_client, auth_scopes)
+          # :nocov:
+          raise NotImplementedError, "#{self.class}#get_grant must be implemented"
+          # :nocov:
+        end
+
+        ##
+        # Refreshes the access token using the OAuth flow.
+        #
+        # It uses `get_grant` to obtain all necessary parameters for the token request.
+        #
+        # @return [OAuth2::AccessToken] A new Token instance.
+        # @raise [RuntimeError] if the token refresh fails.
+        #
+        def refresh_token
+          @token = get_grant(@auth_session, @auth_scopes)
+        rescue StandardError => e
+          raise ZitadelError.new("Failed to refresh token: #{e.message}"), cause: e
+        end
+      end
+    end
+  end
+end

data/lib/zitadel/client/auth/open_id.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require 'net/http'
+
+module Zitadel
+  module Client
+    module Auth
+      ##
+      # OpenId retrieves OpenID Connect configuration from a given host.
+      #
+      # It builds the well-known configuration URL from the provided hostname,
+      # fetches the configuration, and extracts the token endpoint.
+      #
+      class OpenId
+        attr_accessor :token_endpoint, :host_endpoint
+
+        ##
+        # Initializes a new OpenId instance.
+        #
+        # @param hostname [String] the hostname for the OpenID provider.
+        # @raise [RuntimeError] if the OpenID configuration cannot be fetched or the token_endpoint is missing.
+        #
+        # noinspection HttpUrlsUsage
+        def initialize(hostname)
+          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)
+          raise "Failed to fetch OpenID configuration: HTTP #{response.code}" unless response.code.to_i == 200
+
+          config = JSON.parse(response.body)
+          token_endpoint = config['token_endpoint']
+          raise 'token_endpoint not found in OpenID configuration' unless token_endpoint
+
+          @token_endpoint = token_endpoint
+        end
+
+        ##
+        # Builds the well-known OpenID configuration URL for the given hostname.
+        #
+        # @param hostname [String] the hostname for the OpenID provider.
+        # @return [String] the well-known configuration URL.
+        #
+        def self.build_well_known_url(hostname)
+          URI.join(hostname, '/.well-known/openid-configuration').to_s
+        end
+      end
+    end
+  end
+end

data/lib/zitadel/client/auth/personal_access_token_authenticator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Zitadel
+  module Client
+    module Auth
+      ##
+      # Personal Access Token Authenticator.
+      #
+      # Uses a static personal access token for API authentication.
+      #
+      class PersonalAccessTokenAuthenticator < Authenticator
+        ##
+        # Initializes the PersonalAccessTokenAuthenticator with host and token.
+        #
+        # @param host [String] the base URL for the service.
+        # @param token [String] the personal access token.
+        #
+        def initialize(host, token)
+          # noinspection RubyArgCount
+          super(Utils::UrlUtil.build_hostname(host))
+          @token = token
+        end
+
+        protected
+
+        ##
+        # Returns the authentication headers using the personal access token.
+        #
+        # @return [Hash{String => String}] a hash containing the 'Authorization' header.
+        #
+        def auth_headers
+          { 'Authorization' => "Bearer #{@token}" }
+        end
+      end
+    end
+  end
+end

data/lib/zitadel/client/auth/web_token_authenticator.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'openssl'
+
+module Zitadel
+  module Client
+    module Auth
+      # -----------------------------------------------------------------------------
+      # WebTokenAuthenticator
+      # -----------------------------------------------------------------------------
+
+      # OAuth authenticator implementing the JWT bearer flow.
+      #
+      # This implementation builds a JWT assertion dynamically in get_grant().
+      class WebTokenAuthenticator < Auth::OAuthAuthenticator
+        # Constructs a WebTokenAuthenticator.
+        #
+        # @param open_id [OpenId] The OpenId instance with OAuth endpoint information.
+        # @param auth_scopes [Set<String>] The scope(s) for the token request.
+        # @param jwt_issuer [String] The JWT issuer.
+        # @param jwt_subject [String] The JWT subject.
+        # @param jwt_audience [String] The JWT audience.
+        # @param private_key [String] The private key used to sign the JWT.
+        # @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
+        def initialize(open_id, auth_scopes, jwt_issuer, jwt_subject, jwt_audience, private_key,
+                       jwt_lifetime: 3600, jwt_algorithm: 'RS256', key_id: nil)
+          # noinspection RubyArgCount,RubyMismatchedArgumentType
+          super(open_id, auth_scopes, OAuth2::Client.new('zitadel', 'zitadel', {
+                                                           site: open_id.host_endpoint,
+                                                           token_url: open_id.token_endpoint
+                                                         }))
+          @jwt_issuer = jwt_issuer
+          @jwt_subject = jwt_subject
+          @jwt_audience = jwt_audience
+          @private_key = private_key
+          @jwt_lifetime = jwt_lifetime
+          @jwt_algorithm = jwt_algorithm
+          @key_id = key_id
+        end
+
+        # rubocop:enable Metrics/ParameterLists,Metrics/MethodLength
+
+        # Creates a WebTokenAuthenticator instance from a JSON configuration file.
+        #
+        # The JSON file must be formatted as follows:
+        #
+        #   {
+        #     "type": "serviceaccount",
+        #     "keyId": "<key-id>",
+        #     "key": "<private-key>",
+        #     "userId": "<user-id>"
+        #   }
+        #
+        # @param host [String] Base URL for the API endpoints.
+        # @param json_path [String] File path to the JSON configuration file.
+        # @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)
+          config = JSON.parse(File.read(json_path))
+        rescue Errno::ENOENT => e
+          raise "Unable to read JSON file at #{json_path}: #{e.message}"
+        rescue JSON::ParserError => e
+          raise "Invalid JSON in file at #{json_path}: #{e.message}"
+        else
+          raise "Expected a JSON object, got #{config.class}" unless config.is_a?(Hash)
+
+          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
+        end
+
+        # 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.
+        # @return [WebTokenAuthenticatorBuilder] A builder instance.
+        def self.builder(host, user_id, private_key)
+          WebTokenAuthenticatorBuilder.new(host, user_id, user_id, host, private_key)
+        end
+
+        protected
+
+        # Overrides the base get_grant to return client credentials grant parameters.
+        #
+        # @return [OAuth2::AccessToken] A hash containing the grant type.
+        # rubocop:disable Metrics/MethodLength
+        def get_grant(client, auth_scopes)
+          client.assertion.get_token(
+            { iss: @jwt_issuer,
+              sub: @jwt_subject,
+              aud: @jwt_audience,
+              iat: Time.now.utc.to_i,
+              exp: (Time.now.utc + @jwt_lifetime).to_i },
+            {
+              algorithm: @jwt_algorithm,
+              key: OpenSSL::PKey::RSA.new(@private_key),
+              kid: @key_id
+            },
+            {
+              scope: auth_scopes
+            }
+          )
+        end
+
+        # rubocop:enable Metrics/MethodLength
+
+        # -----------------------------------------------------------------------------
+        # WebTokenAuthenticatorBuilder
+        # -----------------------------------------------------------------------------
+
+        # Builder for WebTokenAuthenticator.
+        #
+        # Provides a fluent API for configuring and constructing a WebTokenAuthenticator instance.
+        class WebTokenAuthenticatorBuilder < OAuthAuthenticatorBuilder
+          # Initializes the WebTokenAuthenticatorBuilder with required parameters.
+          #
+          # @param host [String] The base URL for API endpoints.
+          # @param jwt_issuer [String] The issuer claim for the JWT.
+          # @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)
+            # noinspection RubyArgCount
+            super(host)
+            @jwt_issuer = jwt_issuer
+            @jwt_subject = jwt_subject
+            @jwt_audience = jwt_audience
+            @private_key = private_key
+            @jwt_lifetime = 3600
+          end
+
+          # Sets the JWT token lifetime in seconds.
+          #
+          # @param seconds [Integer] Lifetime of the JWT in seconds.
+          # @return [WebTokenAuthenticatorBuilder] The builder instance.
+          def token_lifetime_seconds(seconds)
+            @jwt_lifetime = seconds
+            self
+          end
+
+          def key_identifier(key_id)
+            @key_id = key_id
+            self
+          end
+
+          # Constructs and returns a new WebTokenAuthenticator instance using the configured parameters.
+          #
+          # @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)
+          end
+        end
+      end
+    end
+  end
+end