keycloak_ruby 0.1.0

data/lib/keycloak_ruby/request_performer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/request_performer.rb
+
+module KeycloakRuby
+  # Responsible for performing HTTP requests with HTTParty
+  # and validating the response. This class helps to reduce
+  # FeatureEnvy and keep the Client code cleaner.
+  # :reek:FeatureEnvy
+  class RequestPerformer
+    def initialize(config)
+      @config = config
+    end
+
+    # Executes an HTTP request and verifies the response code.
+    #
+    # @param request_params [KeycloakRuby::RequestParams] - an object containing
+    #   :http_method, :url, :headers, :body, :success_codes, :error_class, :error_message
+    #
+    # @return [HTTParty::Response] The HTTParty response object on success.
+    # @raise [request_params.error_class] If the response code is not in success_codes
+    #   or HTTParty raises an error.
+    def call(request_params)
+      # To reduce FeatureEnvy, extract local variables
+      http_method   = request_params.http_method
+      url           = request_params.url
+      headers       = request_params.headers
+      body          = request_params.body
+
+      response = HTTParty.send(http_method, url, headers: headers, body: body)
+      verify_response!(response, request_params)
+      response
+    rescue HTTParty::Error => e
+      KeycloakRuby.logger.error("#{request_params.error_message} (HTTParty error): #{e.message}")
+      raise request_params.error_class, e.message
+    end
+
+    private
+
+    # Safe validation: returns true/false
+    def verify_response(response, request_params)
+      code          = response.code
+      success_codes = request_params.success_codes
+
+      case success_codes
+      when Range
+        success_codes.cover?(code)
+      when Array
+        success_codes.include?(code)
+      else
+        code == success_codes
+      end
+    end
+
+    # Bang version that raises an error on invalid response
+    def verify_response!(response, request_params)
+      return if verify_response(response, request_params)
+
+      code          = response.code
+      error_message = request_params.error_message
+      KeycloakRuby.logger.error("#{error_message}: #{code} => #{response.body}")
+      raise request_params.error_class, "#{error_message}: #{code} => #{response.body}"
+    end
+  end
+end

data/lib/keycloak_ruby/response_validator.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module KeycloakRuby
+  # Validates Keycloak API responses with both safe and strict modes
+  #
+  # Provides two validation approaches:
+  # 1. Safe validation (#validate) - returns boolean
+  # 2. Strict validation (#validate!) - raises detailed exceptions
+  #
+  # @example Safe validation
+  #   validator = ResponseValidator.new(response)
+  #   if validator.validate
+  #     # proceed with valid response
+  #   else
+  #     # handle invalid response
+  #   end
+  #
+  # @example Strict validation
+  #   begin
+  #     data = ResponseValidator.new(response).validate!
+  #     # use validated data
+  #   rescue KeycloakRuby::Errors::TokenRefreshFailed => e
+  #     # handle error
+  #   end
+  class ResponseValidator
+    # Initialize with the HTTP response
+    # @param response [HTTP::Response] The raw HTTP response from Keycloak
+    def initialize(response)
+      @response = response
+      @data = parse_response_body
+    end
+
+    # Safe validation - returns boolean instead of raising exceptions
+    # @return [Boolean] true if response is valid, false otherwise
+    def validate
+      return false unless valid_http_status?
+      return false if invalid_grant?
+      return false if error_present?
+
+      access_token_present?
+    end
+
+    # Strict validation - raises exceptions for invalid responses
+    # @return [Hash] Parsed response data if valid
+    # @raise [KeycloakRuby::Errors::TokenRefreshFailed] if validation fails
+    def validate!
+      validate or raise_validation_error
+      @data
+    end
+
+    private
+
+    # Parses JSON response body, returns empty hash on failure
+    # @return [Hash]
+    def parse_response_body
+      JSON.parse(@response.body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Checks if HTTP status indicates success
+    # @return [Boolean]
+    def valid_http_status?
+      @response.success?
+    end
+
+    # Checks for OAuth2 "invalid_grant" error
+    # @return [Boolean]
+    def invalid_grant?
+      @data["error"] == "invalid_grant"
+    end
+
+    # Checks for any error in response
+    # @return [Boolean]
+    def error_present?
+      @data.key?("error")
+    end
+
+    # Verifies access token presence
+    # @return [Boolean]
+    def access_token_present?
+      @data["access_token"].present?
+    end
+
+    # Raises appropriate validation error based on failure reason
+    # @raise [KeycloakRuby::Errors::TokenRefreshFailed]
+    def raise_validation_error # rubocop:disable Metrics/MethodLength
+      if !valid_http_status?
+        raise Errors::TokenRefreshFailed,
+              "Keycloak API request failed with status #{@response.code}: #{extract_error_message}"
+      elsif invalid_grant?
+        raise Errors::TokenRefreshFailed,
+              "Invalid grant: #{@data["error_description"] || "Refresh token invalid or expired"}"
+      elsif error_present?
+        raise Errors::TokenRefreshFailed,
+              "Keycloak error: #{@data["error"]} - #{@data["error_description"]}"
+      else
+        raise Errors::TokenRefreshFailed,
+              "Invalid response: access token missing from response"
+      end
+    end
+
+    # Extracts error message from response
+    # @return [String]
+    def extract_error_message
+      if @data["error_description"]
+        @data["error_description"]
+      elsif @response.body.length < 100 # Prevent huge error messages
+        @response.body
+      else
+        "See response body for details"
+      end
+    end
+  end
+end

data/lib/keycloak_ruby/testing/keycloak_helpers.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# keycloak_ruby/testing/keycloak_helpers.rb
+# :reek:UtilityFunction :reek:ControlParameter :reek:ManualDispatch :reek:BooleanParameter :reek:LongParameterList
+module KeycloakRuby
+  module Testing
+    # Helper module for tests with Keycloak
+    module KeycloakHelpers
+      # Combines both sign-in approaches with automatic detection of test type
+      def sign_in(user, test_type: auto_detect_test_type)
+        case test_type
+        when :request
+          mock_token_service(user)
+        when :feature, :system
+          mock_keycloak_login(user, use_capybara: true)
+        else # :controller, :view, etc.
+          mock_keycloak_login(user, use_capybara: false)
+        end
+      end
+
+      # Мокирует авторизацию в request-тестах, подставляя указанного пользователя в current_user.
+      # Нужно, так как в request-тестах нет прямого доступа к сессиям и внешним сервисам авторизации.
+      def mock_token_service(user)
+        token_service_double = instance_double(KeycloakRuby::TokenService, find_user: user)
+        allow(KeycloakRuby::TokenService).to receive(:new).and_return(token_service_double)
+      end
+
+      def create_keycloak_user(username:, email:, password:, temporary:)
+        user_data = KeycloakRuby::User.create(username:, email:, password:, temporary:)
+        KeycloakHelpers.track_keycloak_user(user_data["id"])
+        user_data
+      end
+
+      # Delete all users from Keycloak
+      def self.delete_all_keycloak_users
+        users = KeycloakRuby::User.find("") # Empty search string to find all users
+        users.each do |user|
+          KeycloakRuby::User.delete_by_id(user["id"])
+        end
+      end
+
+      def self.track_keycloak_user(user_id)
+        @keycloak_users ||= []
+        @keycloak_users << user_id
+      end
+
+      def self.cleanup_keycloak_users
+        return unless @keycloak_users
+
+        @keycloak_users.each do |user_id|
+          KeycloakRuby::User.delete(user_id)
+        end
+        @keycloak_users.clear
+      end
+
+      private
+
+      def mock_keycloak_login(user, use_capybara: true)
+        OmniAuth.config.test_mode = true
+        token_data = generate_fake_tokens(user)
+        OmniAuth.config.mock_auth[:keycloak] = token_data
+
+        if use_capybara
+          capybara_login
+        else
+          store_session(token_data.credentials)
+        end
+      end
+
+      def capybara_login
+        visit "/login"
+        click_on I18n.t("user.login") if page.has_button? I18n.t("user.login")
+      end
+
+      def generate_fake_tokens(user)
+        email = user.email
+        token_payload = { "email" => email, "exp" => 2.hours.from_now.to_i }
+
+        OmniAuth::AuthHash.new(provider: "keycloak", uid: "uid-#{email}", info: { email: email },
+                               credentials: OmniAuth::AuthHash.new(
+                                 token: JWT.encode(token_payload, nil, "none"),
+                                 refresh_token: "fake-refresh-#{email}",
+                                 id_token: "fake-id-#{email}",
+                                 expires_at: 2.hours.from_now.to_i
+                               ))
+      end
+
+      def store_session(credentials)
+        session[:access_token]  = credentials[:token]
+        session[:refresh_token] = credentials[:refresh_token]
+        session[:id_token]      = credentials[:id_token]
+      end
+
+      def rspec_auto_detect_test_type
+        if RSpec.current_example.metadata[:type] == :request
+          :request
+        elsif defined?(Capybara::DSL) && Capybara.current_driver != :rack_test
+          :feature
+        else
+          :controller
+        end
+      end
+
+      def auto_detect_test_type
+        if defined?(RSpec) && RSpec.current_example
+          rspec_auto_detect_test_type
+        else
+          :feature
+        end
+      end
+    end
+  end
+end
+# Automatically include in common test frameworks
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include KeycloakRuby::Testing::KeycloakHelpers
+  end
+elsif defined?(Minitest)
+  module Minitest
+    class Test
+      include KeycloakRuby::Testing::KeycloakHelpers
+    end
+  end
+end

data/lib/keycloak_ruby/testing.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/testing.rb
+require_relative "testing/keycloak_helpers"
+
+module KeycloakRuby
+  # Include test methods
+  module Testing
+    def self.included(base)
+      base.include KeycloakHelpers
+    end
+  end
+end

data/lib/keycloak_ruby/token_refresher.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/token_refresher.rb`
+module KeycloakRuby
+  # Handles OAuth2 refresh token flow with Keycloak
+  #
+  # Responsible for:
+  # - Executing refresh token requests
+  # - Validating responses
+  # - Managing refresh failures
+  #
+  # @example Basic usage
+  #   refresher = TokenRefresher.new(session, config)
+  #   new_tokens = refresher.call
+  #
+  # @example With error handling
+  #   begin
+  #     refresher.call
+  #   rescue KeycloakRuby::Errors::TokenRefreshFailed => e
+  #     # Handle token refresh failure (e.g., redirect to login)
+  #   end
+  class TokenRefresher
+    def initialize(session, config)
+      @session = session
+      @config = config
+    end
+
+    # Main entry point - refreshes the token
+    # @return [Hash] New token data if successful
+    # @raise [KeycloakRuby::Errors::TokenRefreshFailed] if refresh fails
+    def call
+      refresh_token_flow
+    end
+
+    private
+
+    def refresh_token_flow
+      log_refresh_attempt
+      response = request_refresh
+      validate_response(response)
+    rescue HTTParty::Error => e
+      handle_http_error(e)
+    end
+
+    def request_refresh
+      HTTParty.post(
+        @config.token_url,
+        body: refresh_params,
+        headers: headers,
+        timeout: 30 # Add timeout for safety
+      )
+    end
+
+    def validate_response(response)
+      validator = ResponseValidator.new(response)
+
+      if validator.validate
+        log_successful_refresh
+        validator.validate! # Returns the validated token data
+      else
+        handle_failed_validation(response)
+      end
+    end
+
+    def handle_http_error(exception)
+      error_message = "Token refresh HTTP error: #{exception.message}"
+      KeycloakRuby.logger.error(error_message)
+      raise Errors::TokenRefreshFailed, error_message
+    end
+
+    # :reek:FeatureEnvy
+    def handle_failed_validation(response)
+      error_message = "Token refresh failed. Status: #{response.code}, Body: #{response.body.truncate(200)}"
+      KeycloakRuby.logger.error(error_message)
+      raise Errors::TokenRefreshFailed, error_message
+    end
+
+    def refresh_params
+      {
+        grant_type: "refresh_token",
+        client_id: @config.oauth_client_id,
+        client_secret: @config.oauth_client_secret,
+        refresh_token: @session[:refresh_token]
+      }
+    end
+
+    def headers
+      {
+        "Content-Type" => "application/x-www-form-urlencoded",
+        "Accept" => "application/json",
+        "User-Agent" => "KeycloakRuby/#{KeycloakRuby::Version::VERSION}"
+      }
+    end
+
+    def log_refresh_attempt
+      KeycloakRuby.logger.info("Attempting token refresh for client: #{@config.oauth_client_id}")
+    end
+
+    def log_successful_refresh
+      KeycloakRuby.logger.info("Successfully refreshed tokens for client: #{@config.oauth_client_id}")
+    end
+  end
+end

data/lib/keycloak_ruby/token_service.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/token_service.rb
+module KeycloakRuby
+  # Service for check and refresh jwt tokens
+  class TokenService
+    def initialize(session, config = KeycloakRuby::Config.new)
+      @session = session
+      @config = config
+      @refresh_mutex = Mutex.new # Mutex ensures only one refresh happens at a time
+    end
+
+    # Finds user by token claims
+    # @return [User, nil]
+    def find_user
+      claims = current_token or return
+      user = ::User.find_by(email: claims["email"])
+      clear_tokens unless user
+      user
+    end
+
+    # Store token
+    def store_tokens(data)
+      @session[:access_token] = extract_access_token(data)
+      @session[:refresh_token] = data["refresh_token"] if data["refresh_token"]
+      @session[:id_token] = data["id_token"] if data["id_token"]
+    end
+
+    def clear_tokens
+      %i[access_token refresh_token id_token].each { |token| @session.delete(token) }
+    end
+
+    private
+
+    # It's necessary, because omniauth return request.env["omniauth.auth"] as 'token', not 'access_token'
+    def extract_access_token(data)
+      data["token"] || data["access_token"]
+    end
+
+    # Gets current token or attempts refresh if expired
+    # @return [Hash, nil] Decoded token claims
+    def current_token
+      token = @session[:access_token] or return
+      decode_token(token)
+    rescue Errors::TokenExpired # Normal refresh
+      refresh_current_token
+    rescue Errors::TokenInvalid => e # Wrong token refresh
+      KeycloakRuby.logger.error("JWT Error: #{e.message}")
+      clear_tokens
+      nil
+    end
+
+    # Decodes JWT token
+    # @raise [Errors::TokenExpired, Errors::TokenInvalid]
+    def decode_token(token)
+      options = jwt_decode_options
+
+      if Rails.env.test?
+        JWT.decode(token, nil, false).first # без проверки подписи в тестах
+      else
+        JWT.decode(token, nil, true, options).first
+      end
+    rescue JWT::ExpiredSignature => e
+      raise Errors::TokenExpired, e.message
+    rescue JWT::DecodeError => e
+      raise Errors::TokenInvalid, e.message
+    end
+
+    def fetch_jwks
+      realm_url = @config.realm_url
+      @fetch_jwks ||= Rails.cache.fetch("keycloak_jwks", expires_in: 1.hour) do
+        uri = URI("#{realm_url}/protocol/openid-connect/certs")
+        JSON.parse(Net::HTTP.get(uri))
+      end
+    end
+
+    # Attempts to refresh the current token
+    def refresh_current_token
+      @refresh_mutex.synchronize do
+        new_tokens = TokenRefresher.new(@session, @config).call
+        store_tokens(new_tokens)
+        decode_token(new_tokens["access_token"])
+      end
+    rescue Errors::TokenRefreshFailed => e
+      KeycloakRuby.logger.error("Refresh failed: #{e.message}")
+      clear_tokens
+      nil
+    end
+
+    # JWT decoding options with JWKS
+    def jwt_decode_options
+      {
+        algorithms: ["RS256"],
+        verify_iss: true,
+        iss: issuer_url,
+        # verify_aud: true, # Вроде рекомендуют, но у нас не работает
+        aud: @config.oauth_client_id,
+        verify_expiration: true,
+        jwks: fetch_jwks
+      }
+    end
+
+    # Constructs issuer URL from configuration
+    def issuer_url
+      @issuer_url ||= @config.realm_url
+    end
+  end
+end

data/lib/keycloak_ruby/user.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/user.rb
+module KeycloakRuby
+  # User-related operations for interacting with Keycloak.
+  # This class provides a simple interface for creating, deleting, and finding users in Keycloak.
+  class User
+    class << self
+      # Creates a new user in Keycloak.
+      #
+      # @param user_attrs [Hash] A hash of user attributes (e.g., :username, :email, :password, :temporary).
+      # @return [Hash] The created user's data.
+      # @raise [KeycloakRuby::Error] If the user creation fails.
+      def create(user_attrs = {})
+        client.create_user(user_attrs)
+      end
+
+      # Deletes users from Keycloak based on a search string.
+      #
+      # @param search_string [String] A string to search for users (e.g., username, email, etc.).
+      # @return [void]
+      # @raise [KeycloakRuby::Error] If any user deletion fails.
+      def delete(search_string)
+        client.delete_users(search_string)
+      end
+
+      # Deletes a user from Keycloak by ID.
+      #
+      # @param user_id [String] The ID of the user to delete.
+      # @return [void]
+      # @raise [KeycloakRuby::Error] If the deletion fails.
+      def delete_by_id(user_id)
+        client.delete_user_by_id(user_id)
+      end
+
+      # Finds users in Keycloak based on a search string.
+      #
+      # @param search_string [String] A string to search for users (e.g., username, email, etc.).
+      # @return [Array<Hash>] An array of user objects (hashes) matching the search criteria.
+      # @raise [KeycloakRuby::Error] If the search fails.
+      def find(search_string)
+        client.find_users(search_string)
+      end
+
+      private
+
+      # Provides a singleton instance of the KeycloakRuby::Client.
+      #
+      # @return [KeycloakRuby::Client] The client instance used for making API requests.
+      def client
+        @client ||= KeycloakRuby::Client.new
+      end
+    end
+  end
+end

data/lib/keycloak_ruby/version.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/version.rb
+# Module for interacting with Keycloak
+module KeycloakRuby
+  # Version module following Semantic Versioning 2.0 guidelines
+  # Provides detailed version information and helper methods
+  #
+  # @example Getting version information
+  #   KeycloakRuby::Version::VERSION      # => "0.1.0"
+  #   KeycloakRuby::Version.to_a          # => [0, 1, 0]
+  #   KeycloakRuby::Version.to_h          # => { major: 0, minor: 1, patch: 0, pre: nil }
+  #   KeycloakRuby.version                # => "0.1.0"
+  #
+  # @example Checking version
+  #   KeycloakRuby::Version >= '0.1.0'    # => true
+  # Module for work with Version
+  module Version
+    # Major version number (incompatible API changes)
+    MAJOR = 0
+    # Minor version number (backwards-compatible functionality)
+    MINOR = 1
+    # Patch version number (backwards-compatible bug fixes)
+    PATCH = 0
+    # Pre-release version (nil for stable releases)
+    PRE = nil
+
+    # Full version string
+    VERSION = [MAJOR, MINOR, PATCH, PRE].compact.join(".").freeze
+
+    # Returns version components as an array
+    # @return [Array<Integer, Integer, Integer, String|nil>]
+    def self.to_a
+      [MAJOR, MINOR, PATCH, PRE]
+    end
+
+    # Returns version components as a hash
+    # @return [Hash<Symbol, Integer|String|nil>]
+    def self.to_h
+      { major: MAJOR, minor: MINOR, patch: PATCH, pre: PRE }
+    end
+
+    # Compares version with another version string
+    # @param version_string [String] version to compare with (e.g., "1.2.3")
+    # @return [Boolean]
+    def self.>=(version_string)
+      Gem::Version.new(VERSION) >= Gem::Version.new(version_string)
+    end
+
+    # Returns the full version string
+    # @return [String]
+    def self.to_s
+      VERSION
+    end
+  end
+
+  # Returns the current gem version
+  # @return [String]
+  def self.version
+    Version::VERSION
+  end
+end