keycloak_ruby 0.1.0

data/README.md

@@ -0,0 +1,157 @@
+# Description
+
+This library is designed to use Keycloak identification in Rails application
+
+## Installation
+
+Add to Gemfile
+
+```bash
+gem "keycloak_ruby", git: "https://github.com/sergey-arkhipov/keycloak_ruby.git"
+
+```
+
+Create initializer for omniauth manually or use generator (config/initializers/omniauth.rb)
+
+```bash
+rails generate keycloak_ruby:install
+```
+
+Now under active development, so you need create manually:
+
+```ruby
+# ApplicationController
+
+  include KeycloakRuby::Authentication
+
+# SeesionController
+  def login
+    render :login, layout: "login"
+  end
+
+  def create
+    auth_info = request.env["omniauth.auth"]
+    keycloak_jwt_service.store_tokens(auth_info[:credentials])
+    user = User.find_by(email: auth_info.dig(:info, :email))
+    return destroy unless user&.active?
+
+    redirect_to root_path, notice: I18n.t("user.auth_success")
+  end
+
+  def destroy
+    id_token = session[:id_token]
+    keycloak_jwt_service.clear_tokens
+    logout_url = "#{KeycloakRuby.config.logout_url}?post_logout_redirect_uri=#{CGI.escape(root_url)}&" \
+                 "id_token_hint=#{id_token}"
+
+    redirect_to logout_url, allow_other_host: true
+  end
+
+# config/routes.rb
+get '/login', to: 'sessions#login', as: :login
+get '/auth/:provider/callback', to: 'sessions#create'
+delete '/logout', to: 'sessions#destroy', as: :logout
+
+```
+
+It is assumed that you have a User model in Rails app
+
+## Architecture Overview
+
+### Component Diagram
+
+```mermaid
+flowchart TD
+    subgraph Rails_Application["Rails Application"]
+        A[Controller] --> B[TokenService]
+        B --> C[TokenRefresher]
+        C --> D[Keycloak Server]
+        D -->|Refresh Token| C
+        C -->|New Tokens| B
+        B --> E[User Model]
+        B --> F[ResponseValidator]
+        C --> F
+        F --> G[Errors]
+        B --> H[JWT Decoder]
+        H --> I[JWKS Cache]
+    end
+
+    style A fill:#ff66ff,stroke:#000000,color:#000000
+    style B fill:#66b3ff,stroke:#000000,color:#000000
+    style C fill:#66b3ff,stroke:#000000,color:#000000
+    style D fill:#ff9933,stroke:#000000,color:#000000
+    style E fill:#66cc66,stroke:#000000,color:#000000
+    style F fill:#66b3ff,stroke:#000000,color:#000000
+    style G fill:#ff6666,stroke:#000000,color:#000000
+    style H fill:#66b3ff,stroke:#000000,color:#000000
+    style I fill:#99ccff,stroke:#000000,color:#000000
+
+    %% Subgraph styling - transparent with black border only
+    style Rails_Application fill:none,stroke:#000000,color:#000000
+
+```
+
+### Authentication Sequence
+
+```mermaid
+sequenceDiagram
+    participant C as Controller
+    participant TS as TokenService
+    participant TR as TokenRefresher
+    participant KS as Keycloak Server
+    participant RV as ResponseValidator
+    participant JD as JWT Decoder
+
+    C->>TS: authenticate(user_credentials)
+    TS->>TR: call()
+    TR->>KS: POST /token
+    KS-->>TR: token_response
+    TR->>RV: validate(response)
+    RV-->>TR: validation_result
+    alt Valid
+        TR-->>TS: new_tokens
+        TS->>JD: decode(access_token)
+        JD->>TS: claims
+        TS-->>C: user
+    else Invalid
+        RV->>TR: raise error
+        TR->>TS: propagate error
+        TS-->>C: nil
+    end
+```
+
+### Key Flows
+
+1. **Initial Authentication**:
+
+   - Controller → TokenService → Keycloak Server
+   - Stores tokens in session
+
+2. **Token Refresh**:
+
+   - TokenService → TokenRefresher → Keycloak Server
+   - Automatic when token expires
+
+3. **Access Validation**:
+
+   - Verifies token signature and claims
+   - Checks user existence in local DB
+
+4. **Error Handling**:
+   - Clear sessions on invalid tokens
+   - Propagates meaningful errors
+
+```
+
+```
+
+## Test
+
+For test purpose there mock helper sign_in(user)
+
+- add `require "keycloak_ruby/testing/keycloak_helpers"` to keycloak_helper.rb
+- add sign_in in tests `config.include KeycloakRuby::Testing::KeycloakHelpers`
+
+```
+
+```

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.verbose = false
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/generators/keycloak_ruby/install_generator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# lib/generators/keycloak_ruby/install_generator.rb
+require "rails/generators"
+
+##
+# Generates the OmniAuth initializer for Keycloak integration
+#
+# Example:
+#   rails generate keycloak_ruby:install
+#
+module KeycloakRuby
+  ##
+  # Rails generator that creates the OmniAuth initializer configuration
+  # for Keycloak authentication
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../templates", __dir__)
+    desc "Creates Keycloak Ruby initializer for OmniAuth configuration"
+
+    ##
+    # Copies the OmniAuth initializer template to the Rails application
+    # unless it already exists
+    def copy_initializer
+      if omniauth_initializer_exists?
+        say_status("skipped", "OmniAuth initializer already exists at #{omniauth_initializer_path}", :yellow)
+      else
+        template "omniauth.rb", "config/initializers/omniauth.rb"
+        say_status("created", "OmniAuth initializer at config/initializers/omniauth.rb", :green)
+      end
+    end
+
+    private
+
+    ##
+    # @return [Pathname] full path to the omniauth initializer
+    def omniauth_initializer_path
+      @omniauth_initializer_path ||= Rails.root.join("config/initializers/omniauth.rb")
+    end
+
+    ##
+    # Checks if the omniauth initializer already exists
+    # @return [Boolean] true if file exists
+    def omniauth_initializer_exists?
+      File.exist?(omniauth_initializer_path)
+    end
+  end
+end

data/lib/keycloak_ruby/authentication.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/authentication.rb
+module KeycloakRuby
+  # Concern to add methods to ApplicationController
+  module Authentication
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :authenticate_user!
+    end
+
+    def keycloak_jwt_service
+      @keycloak_jwt_service ||= KeycloakRuby::TokenService.new(session)
+    end
+
+    def authenticate_user!
+      redirect_to login_path unless current_user&.active?
+    end
+
+    def current_user
+      @current_user ||= keycloak_jwt_service.find_user
+    end
+  end
+end

data/lib/keycloak_ruby/client.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/client.rb
+module KeycloakRuby
+  # Client for interacting with Keycloak (create, delete, and find users, etc.).
+  # rubocop:disable Metrics/ClassLength
+  # rubocop:disable Metrics/MethodLength
+  # :reek:TooManyMethods
+  class Client
+    def initialize(config = KeycloakRuby.config)
+      @config = config
+      @request_performer = RequestPerformer.new(@config)
+    end
+
+    # Authenticates a user with Keycloak and returns token data upon success.
+    #
+    # @param username [String] The user's username or email.
+    # @param password [String] The user's password.
+    # @return [Hash] The token data (access_token, refresh_token, id_token, etc.).
+    # @raise [KeycloakRuby::Errors::InvalidCredentials] If authentication fails.
+    def authenticate_user(username:, password:)
+      body = build_auth_body(username, password)
+      response = http_request(
+        http_method: :post,
+        url: @config.token_url,
+        body: URI.encode_www_form(body),
+        headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+        success_codes: [200],
+        error_class: KeycloakRuby::Errors::InvalidCredentials,
+        error_message: "Failed to authenticate with Keycloak"
+      )
+      response.parsed_response
+    end
+
+    # Creates a user in Keycloak and returns the newly created user's data.
+    #
+    # @param user_attrs [Hash] A hash of user attributes. Must contain:
+    #   :username, :email, :password, :temporary
+    # @option user_attrs [String] :username The username for the new user.
+    # @option user_attrs [String] :email The user's email.
+    # @option user_attrs [String] :password The initial password.
+    # @option user_attrs [Boolean] :temporary Whether to force a password update on first login.
+    #
+    # @raise [KeycloakRuby::Errors::UserCreationError] If user creation fails.
+    # @return [Hash] The newly created user's data.
+    def create_user(user_attrs = {})
+      user_data = build_user_data(user_attrs)
+
+      response = http_request(
+        http_method: :post,
+        url: "#{@config.keycloak_url}/admin/realms/#{@config.realm}/users",
+        headers: default_headers,
+        body: user_data.to_json,
+        success_codes: [201],
+        error_class: KeycloakRuby::Errors::UserCreationError,
+        error_message: "Failed to create Keycloak user"
+      )
+
+      # Extract user ID from the "Location" header, then fetch user details
+      user_id = response.headers["Location"].split("/").last
+      fetch_user(user_id)
+    end
+
+    # Deletes all users that match the provided search string (e.g., username, email).
+    #
+    # @param search_string [String] The search criteria for finding users in Keycloak.
+    # @raise [KeycloakRuby::Errors::UserDeletionError] If any user deletion fails.
+    def delete_users(search_string)
+      user_ids = find_users(search_string).pluck("id")
+      user_ids.each { |id| delete_user_by_id(id) }
+    end
+
+    # Deletes a single user by ID in Keycloak.
+    #
+    # @param user_id [String] The ID of the user to delete.
+    # @raise [KeycloakRuby::Errors::UserDeletionError] If the deletion fails.
+    def delete_user_by_id(user_id)
+      http_request(
+        http_method: :delete,
+        url: "#{@config.keycloak_url}/admin/realms/#{@config.realm}/users/#{user_id}",
+        headers: default_headers,
+        success_codes: [204],
+        error_class: KeycloakRuby::Errors::UserDeletionError,
+        error_message: "Failed to delete Keycloak user with ID #{user_id}"
+      )
+    end
+
+    # Finds all users in Keycloak that match the given search string.
+    #
+    # @param search [String] The search query (e.g., part of username or email).
+    # @return [Array<Hash>] An array of user objects.
+    # @raise [KeycloakRuby::Errors::APIError] If the request fails.
+    def find_users(search)
+      response = http_request(
+        http_method: :get,
+        url: "#{@config.keycloak_url}/admin/realms/#{@config.realm}/users/?search=#{search}",
+        headers: default_headers,
+        success_codes: [200],
+        error_class: KeycloakRuby::Errors::APIError,
+        error_message: "Failed to get Keycloak users"
+      )
+      JSON.parse(response.body)
+    end
+
+    # Updates the redirect URIs for a specific client in Keycloak.
+    #
+    # @param client_id [String] The client ID in Keycloak.
+    # @param redirect_uris [Array<String>] A list of valid redirect URIs for this client.
+    # @raise [KeycloakRuby::Errors::ConnectionError] If the update request fails.
+    def update_client_redirect_uris(client_id:, redirect_uris:)
+      client_record = find_client_by_id(client_id)
+      update_redirect_uris_for(client_record["id"], redirect_uris)
+    end
+
+    private
+
+    def build_auth_body(username, password)
+      {
+        client_id: @config.oauth_client_id,
+        client_secret: @config.oauth_client_secret,
+        username: username,
+        password: password,
+        grant_type: "password"
+      }
+    end
+
+    def build_user_data(attrs)
+      { username: attrs.fetch(:username), email: attrs.fetch(:email), enabled: true,
+        credentials: [
+          {
+            type: "password",
+            value: attrs.fetch(:password),
+            temporary: attrs.fetch(:temporary, true)
+          }
+        ] }
+    end
+
+    # Builds RequestParams and passes them to the RequestPerformer.
+    def http_request(options = {})
+      params = build_request_params(options)
+      @request_performer.call(params)
+    end
+
+    def build_request_params(opts)
+      RequestParams.new(
+        http_method: opts.fetch(:http_method),
+        url: opts.fetch(:url),
+        headers: opts.fetch(:headers, {}),
+        body: opts.fetch(:body, nil),
+        success_codes: opts.fetch(:success_codes, [200]),
+        error_class: opts.fetch(:error_class, KeycloakRuby::Errors::APIError),
+        error_message: opts.fetch(:error_message, "Request failed")
+      )
+    end
+
+    # Retrieves client details by its "clientId".
+    #
+    # @param client_id [String] The "clientId" in Keycloak.
+    # @return [Hash] The client details.
+    # @raise [KeycloakRuby::Errors::ClientError] If no matching client is found or the request fails.
+    def find_client_by_id(client_id)
+      response = http_request(
+        http_method: :get,
+        url: "#{@config.keycloak_url}/admin/realms/#{@config.realm}/clients",
+        headers: default_headers,
+        success_codes: [200],
+        error_class: KeycloakRuby::Errors::ClientError,
+        error_message: "Failed to fetch clients"
+      )
+
+      clients = JSON.parse(response.body)
+      client_record = clients.find { |client| client["clientId"] == client_id }
+      raise KeycloakRuby::Errors::ClientError, "Client #{client_id} not found" unless client_record
+
+      client_record
+    end
+
+    # Performs a PUT request to update the redirect URIs for a given client in Keycloak.
+    #
+    # @param client_id [String] The internal Keycloak client ID.
+    # @param redirect_uris [Array<String>] List of valid redirect URIs for this client.
+    # @raise [KeycloakRuby::Errors::ConnectionError] If the update request fails.
+    def update_redirect_uris_for(client_id, redirect_uris)
+      http_request(
+        http_method: :put,
+        url: "#{@config.keycloak_url}/admin/realms/#{@config.realm}/clients/#{client_id}",
+        headers: default_headers,
+        body: { redirectUris: redirect_uris }.to_json,
+        success_codes: (200..299),
+        error_class: KeycloakRuby::Errors::ConnectionError,
+        error_message: "Failed to update redirectUris for client #{client_id}"
+      )
+    end
+
+    # Fetches a user by ID from Keycloak.
+    #
+    # @param user_id [String] The user's ID in Keycloak.
+    # @return [Hash] The Keycloak user data.
+    # @raise [KeycloakRuby::Errors::UserNotFound] If the user cannot be found or the request fails.
+    def fetch_user(user_id)
+      response = http_request(
+        http_method: :get,
+        url: "#{@config.keycloak_url}/admin/realms/#{@config.realm}/users/#{user_id}",
+        headers: default_headers,
+        success_codes: [200],
+        error_class: KeycloakRuby::Errors::UserNotFound,
+        error_message: "Failed to fetch Keycloak user with ID #{user_id}"
+      )
+
+      response.parsed_response
+    end
+
+    # Retrieves the admin token used to authenticate calls to the Keycloak Admin API.
+    #
+    # @return [String] The admin access token.
+    # @raise [KeycloakRuby::Errors::TokenVerificationFailed] If the token request fails.
+    def admin_token
+      body = {
+        client_id: @config.admin_client_id,
+        client_secret: @config.admin_client_secret,
+        grant_type: "client_credentials"
+      }
+
+      response = http_request(
+        http_method: :post,
+        url: "#{@config.keycloak_url}/realms/#{@config.realm}/protocol/openid-connect/token",
+        headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+        body: URI.encode_www_form(body),
+        success_codes: [200],
+        error_class: KeycloakRuby::Errors::TokenVerificationFailed,
+        error_message: "Failed to get Keycloak admin token"
+      )
+
+      response.parsed_response["access_token"]
+    end
+
+    # Returns a set of default headers for requests requiring the admin token.
+    #
+    # @return [Hash] A headers Hash including Authorization and Content-Type.
+    def default_headers
+      {
+        "Authorization" => "Bearer #{admin_token}",
+        "Content-Type" => "application/json"
+      }
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+  # rubocop:enable Metrics/MethodLength
+end

data/lib/keycloak_ruby/config.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/config.rb
+module KeycloakRuby
+  # Configuration class for Keycloak Ruby gem.
+  #
+  # Handles loading and validation of Keycloak configuration from either:
+  # - A YAML file (default: config/keycloak.yml)
+  # - Direct attribute assignment
+  #
+  # == Example YAML Configuration
+  #
+  #   development:
+  #     keycloak_url: "https://keycloak.example.com"
+  #     app_host: "http://localhost:3000"
+  #     realm: "my-realm"
+  #     oauth_client_id: "my-client"
+  #     oauth_client_secret: "secret"
+  #
+  # == Example Programmatic Configuration
+  #
+  #   config = KeycloakRuby::Config.new
+  #   config.keycloak_url = "https://keycloak.example.com"
+  #   config.realm = "my-realm"
+  #   # ... etc
+  # :reek:MissingSafeMethod
+  class Config
+    # Default path to configuration file (Rails.root/config/keycloak.yml)
+    DEFAULT_CONFIG_PATH = if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+                            Rails.root.join("config", "keycloak.yml")
+                          else
+                            # Fallback for non-Rails or when Rails isn't loaded yet
+                            File.expand_path("config/keycloak.yml", Dir.pwd)
+                          end
+    REQUIRED_ATTRIBUTES = %i[
+      keycloak_url
+      app_host
+      realm
+      oauth_client_id
+      oauth_client_secret
+    ].freeze
+    # :reek:Attribute
+    attr_accessor :keycloak_url,
+                  :app_host,
+                  :realm,
+                  :admin_client_id,
+                  :admin_client_secret,
+                  :oauth_client_id,
+                  :oauth_client_secret
+
+    attr_reader :config_path
+
+    # Initialize configuration, optionally loading from YAML file
+    #
+    # @param config_path [String] Path to YAML config file (default: config/keycloak.yml)
+    #
+    #
+    def initialize(config_path = DEFAULT_CONFIG_PATH)
+      @config_path = config_path
+      load_config
+    end
+
+    # Validates that all required configuration attributes are present
+    #
+    # @raise [KeycloakRuby::Errors::ConfigurationError] if any required attribute is missing
+    #
+
+    def validate!
+      REQUIRED_ATTRIBUTES.each do |attr|
+        value = public_send(attr)
+        raise Errors::ConfigurationError, "#{attr} is required" if value.blank?
+      end
+    end
+
+    def realm_url
+      "#{keycloak_url}/realms/#{realm}"
+    end
+
+    def redirect_url
+      "#{app_host}/auth/keycloak/callback"
+    end
+
+    def logout_url
+      "#{realm_url}/protocol/openid-connect/logout"
+    end
+
+    def token_url
+      "#{realm_url}/protocol/openid-connect/token"
+    end
+
+    private
+
+    # Loads configuration from YAML file if it exists
+    # :reek:ManualDispatch
+    def load_config
+      return unless File.exist?(@config_path)
+
+      yaml_content = load_yaml_file
+      env_config = yaml_content[current_env] || {}
+      apply_config(env_config)
+    end
+
+    def load_yaml_file
+      YAML.safe_load(ERB.new(File.read(@config_path)).result, aliases: true)
+    end
+
+    def current_env
+      defined?(Rails) ? Rails.env : ENV["APP_ENV"] || "development"
+    end
+
+    def apply_config(config_hash)
+      config_hash.each do |key, value|
+        setter = :"#{key}="
+        public_send(setter, value) if respond_to?(setter)
+      end
+    end
+  end
+end

data/lib/keycloak_ruby/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/errors.rb
+module KeycloakRuby
+  # Namespace for all KeycloakRuby specific errors
+  # Follows a hierarchical structure for better error handling
+  module Errors
+    # Base error class for all KeycloakRuby errors
+    # All custom errors inherit from this class
+    class Error < StandardError; end
+
+    ## Configuration Related Errors ##
+
+    # Raised when there's an issue with gem configuration
+    class ConfigurationError < Error; end
+
+    ## Authentication Related Errors ##
+
+    # Base class for authentication failures
+    class AuthenticationError < Error; end
+
+    # Raised when user credentials are invalid
+    class InvalidCredentials < AuthenticationError; end
+
+    # Raised when user account is not found
+    class UserNotFound < AuthenticationError; end
+
+    # Raised when account is temporarily locked
+    class AccountLocked < AuthenticationError; end
+
+    ## User Management Errors ##
+
+    # Raised when user creation fails
+    class UserCreationError < Error; end
+
+    # Raised when user update fails
+    class UserUpdateError < Error; end
+
+    # Raised when user deletion fails
+    class UserDeletionError < Error; end
+
+    ## Token Related Errors ##
+
+    # Base class for all token-related errors
+    class TokenError < Error; end
+
+    # Raised when token has expired +
+    class TokenExpired < TokenError; end
+
+    # Raised when token is invalid (malformed, wrong signature, etc.)
+    class TokenInvalid < TokenError; end
+
+    # Raised when token refresh fails
+    class TokenRefreshFailed < TokenError; end
+
+    # Raised when token verification fails
+    class TokenVerificationFailed < TokenError; end
+
+    ## API Communication Errors ##
+
+    # Raised when API request fails
+    class APIError < Error; end
+
+    # Raised when receiving 4xx responses from Keycloak
+    class ClientError < APIError; end
+
+    # Raised when receiving 5xx responses from Keycloak
+    class ServerError < APIError; end
+
+    # Raised when connection to Keycloak fails
+    class ConnectionError < APIError; end
+  end
+end

data/lib/keycloak_ruby/request_params.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# lib/keycloak_ruby/request_params.rb
+module KeycloakRuby
+  # A small, typed struct for request parameters
+  RequestParams = Struct.new(
+    :http_method,
+    :url,
+    :headers,
+    :body,
+    :success_codes,
+    :error_class,
+    :error_message,
+    keyword_init: true
+  )
+end