keycloak_rails 1.0.0.pre.beta

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f02d892062dce2d81c45f4de13d30c78201eb376675a47bb91b1292ac8963487
+  data.tar.gz: a8272329fa865c85099399b1f819c525aa65483c0cd13cf6e711a18525d9f866
+SHA512:
+  metadata.gz: df5bf2f2e77dacbf7c6211ccdf70adb1046398a46d94f31777af3c2987085b1db30fc95daead3dcde8b838105cd69f1ee42d1f407ea3c7f35eb869af6fd58e42
+  data.tar.gz: 4d43eaffc5aafd0822c399a6ee45e31e135e01abd72b4fdd79c1beef773c14672d814eda9edf9336b61c97a05ec1fba1cb13431d91c2966d1a9e2cceff55dd8b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Nucleus Healthcare LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,184 @@
+# KeycloakRails
+Keycloak_rails is an api wrapper for open source project [Keycloak](https://www.keycloak.org/)
+
+* the gem assumes that you have a configured and ready to use keycloak server
+* the gem is still in beta and the docs does not reflect the latest updates, multiple bugs might occur
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "keycloak_rails"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install keycloak_rails
+```
+
+## Getting started
+to generate keycloack_rails initializer execute:
+```bash
+$ bundle exec rails g keycloak_rails:config
+```
+ 
+go to `config/initializers/keycloack_rails.rb`
+
+where you will find 
+```ruby
+# frozen_string_literal: true
+
+# Keycloak Rails initializer
+
+KeycloakRails.configure do |config|
+  ####################################################
+  # Rails app controllers to manage auth
+  # config.sessions_controller = 'sessions'
+  # config.registrations_controller = 'registrations'
+  # config.unlocks_controller = 'unlocks'
+  # config.passwords_controller = 'passwords'
+  # config.omniauth_controller = 'omniauth'
+  ####################################################
+  # keyclaok rails need your user model name
+  # config.user_model = 'user'
+  ####################################################
+  # Auth server info
+  # config.auth_server_url = ''
+  # config.realm = 'realm'
+  # config.public_key = "public_key"
+  # config.secret = ''
+  # config.client_id = 'client_id'
+  ####################################################
+end
+```
+uncomment config options and enter your apps info
+
+**Note** do not uncomment controller config if you just want to use keycloak_rails user/client helpers
+
+## use
+### with controller helpers
+if you decided to use all of keycloak rails functionallity (pass controller options) keycloack rails will automatically hook up to named controllers and extend the base classes with our controller concerns which will provide the following methods
+#### KeycloakRails::Controller::Helpers
+***
+This concern will be inherited by all controllers as it extends application controller
+
+the following helpers will be added to your app 
+```ruby
+ensure_active_session # redirects to root if user not logged in
+ensure_no_active_session # redirects to root if user is logged in
+current_user # returns current user by session cookie
+user_has_active_sso_session? # returns true if current user has an active session in auth server
+```
+
+#### KeycloakRails::Controller::Sessions
+***
+extends the controller passed to `KeycloakRails.config.sessions_controller`
+
+In your app 
+
+
+`keycloak_rails.rb`
+```ruby
+KeycloakRails.configure do |config|
+   config.sessions_controller = 'sessions'
+end
+```
+
+`app/controllers/sessions_controller.rb`
+```ruby
+class SessionsController < ApplicationController
+  skip_before_action :ensure_active_session, only: %i[new log_in]
+  before_action :ensure_no_active_session, only: %i[new log_in]
+
+  def new; end
+
+  def log_in
+    start_sso_session(params[:email], params[:password])
+    # keycloak_rails will take care of setting the session cookie & current_user for you
+  end
+
+  def log_out
+    end_sso_session
+  end
+end
+```
+
+
+#### KeycloakRails::Controller::Registrations
+***
+The main idea behind keycloack_rails is to make adding sso easy to an existing rails app thats already in prod, and the registrations module is the backbone to achive that.
+
+In your app 
+
+
+`keycloak_rails.rb`
+```ruby
+KeycloakRails.configure do |config|
+   config.registrations_controller = 'registrations'
+end
+```
+
+`app/controllers/registrations_controller.rb`
+```ruby
+class RegistrationsController < ApplicationController
+  skip_before_action :ensure_active_session, only: %i[new create_user]
+  before_action :ensure_no_active_session, only: %i[new create_user]
+  
+  def new; end
+
+  def sign_up
+    sso_user = create_sso_user(email: params[:email], password: params[:password],
+                               first_name: params[:first_name], last_name: params[:last_name])
+    user = User.create!(sso_user)
+    # sso_user = { sso_sub: user_keycloak_sub, 
+    #              email: params[:email], 
+    #              first_name: params[:first_name], 
+    #              last_name: params[:last_name] }
+    # as shown above the sso_sub returned from will need to be added to the DB user record
+    # the sso sub is a uniqe identifier generated by keycloak auth server
+    # it can be used to link multiple apps together
+    if user
+      render json: user
+    else 
+      render json: user.errors
+    end
+  end
+  
+  
+end
+```
+
+#### KeycloakRails::Controller::Passwords
+***
+#### KeycloakRails::Controller::Unlocks
+***
+#### KeycloakRails::Controller::Omniauth
+***
+
+### without controller helpers
+#### KeycloakRails::User
+
+#### KeycloakRails::Client
+
+
+## Architecte plan
+
+### Engine Strecture
+<img width="573" alt="Screen Shot 2022-11-20 at 1 11 50 AM" src="https://user-images.githubusercontent.com/84993125/202890379-b7f8abe9-105c-4d7d-bdf8-c5768f4111af.png">
+
+### Some use cases
+|auth request|redirect|protected route request
+|:-:|:-:|:-:|
+|![auth request](https://user-images.githubusercontent.com/84993125/202890457-7d58c789-368a-4423-9064-4c50a8ffa296.png)|![redirect](https://user-images.githubusercontent.com/84993125/202890476-2420025e-0f23-4102-8a63-e961411eff16.png)|![protected route request](https://user-images.githubusercontent.com/84993125/202890490-854bda28-2dd3-41b8-8f06-ce80de4825e9.png)
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/app/models/keycloak_rails/concerns/sso_recipient.rb

@@ -0,0 +1,13 @@
+module KeycloakRails
+  module SsoRecipient
+    extend ActiveSupport::Concern
+
+    included do
+      has_one :keycloak_rails_sso, as: :recipient, class_name: "::KeycloakRails::Sso"
+
+      def sub
+        keycloak_rails_sso.sub
+      end
+    end
+  end
+end

data/lib/app/models/keycloak_rails/sso.rb

@@ -0,0 +1,5 @@
+module KeycloakRails
+  class Sso < ActiveRecord::Base
+    belongs_to :recipient, polymorphic: true
+  end
+end

data/lib/generators/keycloak_rails/config/config_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root(File.expand_path(File.dirname(__FILE__)))
+      def copy_initializer
+        copy_file '../keycloak_rails.rb', 'config/initializers/keycloak_rails.rb'
+      end
+    end
+  end
+end

data/lib/generators/keycloak_rails/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root(File.expand_path(File.dirname(__FILE__)))
+
+      TABLE_NAME = 'keycloak_rails_sso'.freeze
+
+      desc "Generates a name space SSO model to store user subs."
+
+      def generate_keycloak_rails_model
+        generate :migration, "create_#{TABLE_NAME}", "recipient:references{polymorphic}",  "sub:string:index"
+      end
+    end
+  end
+end

data/lib/generators/keycloak_rails/keycloak_rails.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Keycloak Rails initializer
+
+KeycloakRails.configure do |config|
+  ####################################################
+  # config options
+  # decode token strategy can be :local or :cloud
+  # config.decode_token_strategy = :local
+  # config.signature_algo = 'RS256'
+  # config.allow_magic_links = true
+  ####################################################
+  # Rails app controllers to manage auth
+  # config.sessions_controller = 'sessions'
+  # config.registrations_controller = 'registrations'
+  # config.unlocks_controller = 'unlocks'
+  # config.passwords_controller = 'passwords'
+  # config.omniauth_controller = 'omniauth'
+  ####################################################
+  # Rails app models
+  # config.user_model = 'user'
+  ####################################################
+  # Auth server info
+  # config.auth_server_url = ''
+  # config.realm = 'realm'
+  # only needed if decode_token_strategy = :local
+  # config.public_key = "public_key"
+  # config.secret = ''
+  # config.client_id = 'client_id'
+  ####################################################
+end

data/lib/keycloak_rails/client.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # client lvl access to sso server established with client id and secret
+  # can use basic auth or bearer client_token
+  # perms for this lvl of access are controllered by sso server client roles
+  class Client
+    def initialize
+      @curl = KeycloakRails::Curl.new
+    end
+
+    def create_user(email:, password:, first_name:, last_name:)
+      request = @curl.post(path: "admin/realms/#{KeycloakRails.realm}/users",
+                           headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                           body: { username: email, email: email, firstName: first_name, lastName: last_name,
+                                   attributes: {}, groups: [], enabled: true }.to_json)
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      set_perm_password(email, password)
+    end
+
+    def current_user_has_active_session?
+      KeycloakRails.currnet_session_cookie && current_cookie_active?
+    end
+
+    def current_cookie_active?
+      token_introspection['active'] ? true : KeycloakRails.destroy_auth_cookies
+    end
+
+    # private
+
+    def token_introspection
+      request = @curl.post(path: KeycloakRails.openid_config['introspection_endpoint'],
+                           headers: { 'Authorization': basic_auth_token,
+                                      'Content-Type': 'application/x-www-form-urlencoded' },
+                           body: { "token": KeycloakRails.currnet_session_cookie })
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def verify_email(user_id)
+      request = @curl.put(path: "/admin/realms/#{KeycloakRails.realm}/users/#{user_id}",
+                          headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                          body: { "emailVerified": true }.to_json)
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def update_user_attributes(user_id, attributes)
+      request = @curl.put(path: "/admin/realms/#{KeycloakRails.realm}/users/#{user_id}",
+                          headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                          body: attributes.to_json)
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def require_set_otp(user_email)
+      user = user_by_username(user_email)
+      required_actions = user['requiredActions'].push("CONFIGURE_TOTP")
+      request = @curl.put(path: "/admin/realms/#{KeycloakRails.realm}/users/#{user['id']}",
+                          headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                          body: { "requiredActions": required_actions }.to_json)
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def set_perm_password(email, password)
+      user = user_by_username(email)
+      request = @curl.put(path: "/admin/realms/#{KeycloakRails.realm}/users/#{user['id']}/reset-password",
+                          headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                          body: { 'type': 'password', 'temporary': false, 'value': password }.to_json)
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def get_magic_link(email:, redirect_uri:, expiration_seconds: 3600, force_create: false, send_email: false, client_id: KeycloakRails.client_id)
+      request = @curl.post(path: "/auth/realms/#{KeycloakRails.realm}/magic-link",
+                           headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                           body: { "email": email, "client_id": client_id,
+                                   "redirect_uri": redirect_uri, "expiration_seconds": expiration_seconds,
+                                   "force_create": force_create, "update_profile": force_create,
+                                   "send_email": send_email }.to_json)
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def user_by_username(email)
+      request = @curl.get(path: "admin/realms/#{KeycloakRails.realm}/users?username=#{email}&exact=true",
+                          headers: { 'Authorization': client_token, 'Content-Type': 'application/json' },
+                          body: { username: email, exact: true }.to_json)
+
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]&.first
+    end
+
+    def basic_auth_token
+      "Basic #{Base64.strict_encode64("#{KeycloakRails.client_id}:#{KeycloakRails.secret}")}"
+    end
+
+    #  <---- USE WISELY!!!! ----->
+    def client_token
+      "bearer #{fetch_client_token['access_token']}"
+    end
+
+    def fetch_client_token
+      request = @curl.post(path: "realms/#{KeycloakRails.realm}/protocol/openid-connect/token",
+                           headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                           body: { 'grant_type': 'client_credentials', 'client_id': KeycloakRails.client_id,
+                                   'client_secret': KeycloakRails.secret })
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+  end
+end

data/lib/keycloak_rails/controller/helpers.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to ActionController::Base class
+    module Helpers
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :generate_magic_link, :current_user
+
+        def initialize
+          kick_start_auth_server_connection
+          set_auth_cookies_procs
+          set_destroy_auth_cookies
+          super
+        end
+
+        def ensure_active_session(accept_magic_link_handshake: false)
+          redirect_to root_path unless user_has_active_sso_session?(accept_magic_link_handshake: accept_magic_link_handshake)
+        end
+
+        def ensure_no_active_session
+          redirect_to root_path if user_has_active_sso_session?
+        end
+
+        def user_has_active_sso_session?(accept_magic_link_handshake: false)
+          (keycloak_client.current_user_has_active_session? && current_user) ||
+            (accept_magic_link_handshake && ensure_magic_link_code)
+        end
+
+        def keycloak_client
+          @keycloak_client ||= KeycloakRails::Client.new
+        end
+
+        def keycloak_user
+          @keycloak_user ||= KeycloakRails::User.new
+        end
+
+        # need to think of away to capture the user model if we wanna set current_user
+        # initial thought: use Dry::Configurable object defined on the Keycloak module to capture the model name and meta program my way from there
+        def current_user
+          @current_user ||= KeycloakRails::Sso.includes(:recipient).find_by(sub: keycloak_user.active_user_sub)&.recipient
+          # have a join table keycloak_rails_subs sso_sub:string #{KeycloakRails.user_model}_id:refrence
+          # to KeycloakRails.user_model.rb and add has_one :keycloak_rails_sub
+          # delegate sso_sub to {KeycloakRails.user_model}
+          #
+        end
+
+        def destroy_current_user
+          @current_user = nil
+        end
+
+        def destroy_session_cookie
+          cookies.permanent[:keycloak_session_token] = nil
+        end
+
+        def kick_start_auth_server_connection
+          keycloak_client
+          keycloak_user
+        end
+
+        def set_auth_cookies_procs
+          KeycloakRails.session_cookie_proc = -> { cookies.encrypted.permanent[:keycloak_session_token] }
+          KeycloakRails.refresh_cookie_proc = -> { cookies.encrypted.permanent[:keycloak_refresh_token] }
+        end
+
+        def set_auth_cookies(tokens)
+          cookies.encrypted.permanent[:keycloak_session_token] = tokens['access_token']
+          cookies.encrypted.permanent[:keycloak_refresh_token] = tokens['refresh_token']
+          true
+        end
+
+        def set_destroy_auth_cookies
+          KeycloakRails.destroy_session_cookie_proc = -> { cookies.permanent[:keycloak_session_token] = nil }
+          KeycloakRails.destroy_refresh_cookie_proc = -> { cookies.permanent[:keycloak_refresh_token] = nil }
+        end
+      end
+    end
+  end
+end

data/lib/keycloak_rails/controller/magic_links.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to ActionController::Base class
+    # only loaded if KeycloakRails.allow_magic_link = true
+    module MagicLinks
+      extend ActiveSupport::Concern
+
+      included do
+        
+        def generate_magic_link(url:, email: , expiration_seconds: 3600, force_create: false, send_email: false, client_id: KeycloakRails.client_id)
+          magic_link_obj = keycloak_client.get_magic_link(email: email,
+                                                          redirect_uri: url,
+                                                          expiration_seconds: expiration_seconds,
+                                                          force_create: force_create,
+                                                          send_email: send_email,
+                                                          client_id: client_id)
+          magic_link_obj.except(force_create ? nil : 'user_id')
+                        .except(send_email ? nil : 'sent')
+        end
+
+        def ensure_magic_link_code
+          return false unless magic_link_params[:code] && magic_link_params[:session_state]
+          return false unless login_by_handshake
+
+          true
+        end
+
+        def login_by_handshake(persist_session: true)
+          redirect_uri = url_for(only_path: false, overwrite_params: nil)
+          tokens = keycloak_user.fetch_tokens_by_handshake(code: magic_link_params[:code], redirect_uri: redirect_uri)
+          persist_session ? set_auth_cookies(tokens) : tokens
+        end
+
+        def client_user?
+          !!current_user
+        end
+
+        def magic_link_params
+          params.permit(:session_state, :code)
+        end
+      end
+    end
+  end
+end

data/lib/keycloak_rails/controller/omniauth.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to KeycloakRails.omniauth controller
+    module Omniauth
+      extend ActiveSupport::Concern
+
+      included do
+
+      end
+    end
+  end
+end

data/lib/keycloak_rails/controller/passwords.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to KeycloakRails passwords controller
+    module Passwords
+      extend ActiveSupport::Concern
+
+      included do
+        def reset_password(new_password:, new_password_confirmation:, email: current_user.email)
+          raise StandardError, 'Passwords must match' unless new_password == new_password_confirmation
+
+          keycloak_client.set_perm_password(email, new_password)
+        end
+      end
+    end
+  end
+end

data/lib/keycloak_rails/controller/registrations.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to KeycloakRails.registrations controller
+    module Registrations
+      extend ActiveSupport::Concern
+
+      included do
+        def create_or_find_sso_user(email:, password:, first_name:, last_name:, password_confirmation: nil, set_session: true)
+          user = keycloak_client.user_by_username(email)
+          if user
+            { sso_sub: user['id'], email: email,
+              first_name: first_name, last_name: last_name }
+          else
+            create_sso_user(email: email, password: password, first_name: first_name, last_name: last_name, password_confirmation: password_confirmation, set_session: set_session)
+          end
+        end
+
+        def create_sso_user(email:, password:, first_name:, last_name:, password_confirmation: nil, set_session: true)
+          raise StandardError, 'Passwords must match' if password_confirmation && password != password_confirmation
+
+          keycloak_client.create_user(email: email,
+                                      password: password,
+                                      first_name: first_name,
+                                      last_name: last_name)
+          if set_session
+            tokens = keycloak_user.fetch_tokens(email: email, password: password)
+            set_auth_cookies(tokens)
+          end
+          { sso_sub: keycloak_user.active_user_sub, email: email,
+            first_name: first_name, last_name: last_name }
+        end
+
+        def update_sso_record_attributes(user_sub, attributes)
+          attributes = attributes.transform_keys { |key| key.to_s.camelize(:lower) }
+          keycloak_client.update_user_attributes(user_sub, attributes)
+        end
+
+        def mark_email_verified(user_sub)
+          keycloak_client.verify_email(user_sub)
+        end
+      end
+    end
+  end
+end

data/lib/keycloak_rails/controller/sessions.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to KeycloakRails.sessions controller
+    module Sessions
+      extend ActiveSupport::Concern
+
+      included do
+        def start_sso_session(email, password)
+          tokens = keycloak_user.fetch_tokens(email: email, password: password)
+          set_auth_cookies(tokens)
+          current_user
+          redirect_to_app_root
+        end
+
+        def end_sso_session
+          redirect_uri = url_for(only_path: false, overwrite_params: nil)
+          keycloak_user.end_session(redirect_uri)
+          destroy_current_user
+          KeycloakRails.destroy_auth_cookies
+          redirect_to_app_root
+        end
+
+        def redirect_to_app_root
+          # redirect_back(fallback_location: root_path)
+          redirect_to root_path
+        end
+      end
+    end
+  end
+end

data/lib/keycloak_rails/controller/unlocks.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # name space
+  module Controller
+    # controller helpers added to KeycloakRails.unlocks controller
+    module Unlocks
+      extend ActiveSupport::Concern
+
+      included do
+
+      end
+    end
+  end
+end

data/lib/keycloak_rails/curl.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # https client with farady v > 2.0.0
+  class Curl
+    def initialize
+      @faraday = Faraday.new(url: KeycloakRails.auth_server_url)
+    end
+
+    def post(path: '', headers: { 'Content-Type': 'application/json' }, body: {})
+      request = @faraday.post(path) do |req|
+        req.headers = headers
+        req.body = body
+      end
+      extract_response(request)
+    end
+
+    def get(path: '', headers: { 'Content-Type': 'application/json' }, body: {})
+      request = @faraday.get(path) do |req|
+        req.headers = headers
+        req.body = body
+      end
+      extract_response(request)
+    end
+
+    def patch(path: '', headers: { 'Content-Type': 'application/json' }, body: {})
+      request = @faraday.patch(path) do |req|
+        req.headers = headers
+        req.body = body
+      end
+      extract_response(request)
+    end
+
+    def put(path: '', headers: { 'Content-Type': 'application/json' }, body: {})
+      request = @faraday.put(path) do |req|
+        req.headers = headers
+        req.body = body
+      end
+      extract_response(request)
+    end
+
+    private
+
+    def extract_response(request)
+      case request.status
+      when 200..299 then response_to request, message: 'succeeded', status: :ok
+      when 300..399 then response_to request, message: 'succeeded', status: :ok
+      when 400..499 then response_to request, message: 'something went wrong', status: :unprocessed
+      when 500..599 then response_to request, message: 'something went wrong', status: :unprocessed
+      else response_to request, message: 'something went wrong', status: :unprocessed
+      end
+    end
+
+    def response_to(request, message: "", status: :ok)
+      { response: request.body && request.body != '' ? JSON.parse(request.body) : {}, message: message, status: status }
+    end
+  end
+end

data/lib/keycloak_rails/engine.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  class Engine < ::Rails::Engine
+    isolate_namespace(KeycloakRails)
+
+    initializer('keycloack_rails', after: :load_config_initializers) do
+      ActionController::Base.include KeycloakRails::Controller::Helpers
+      ActionController::Base.include KeycloakRails::Controller::Sessions
+      ActionController::Base.include KeycloakRails::Controller::Registrations
+      ActionController::Base.include KeycloakRails::Controller::Passwords
+      ActionController::Base.include KeycloakRails::Controller::MagicLinks if KeycloakRails.allow_magic_links
+    end
+
+    config.after_initialize do
+      if KeycloakRails.user_model
+        user_klass = KeycloakRails.user_model
+        user_klass.singularize.classify.constantize.include KeycloakRails::SsoRecipient
+      end
+    end
+  end
+end

data/lib/keycloak_rails/user.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module KeycloakRails
+  # User lvl access to sso server established session_token after auth with username and password
+  # min perms
+  class User
+    def initialize
+      @curl = KeycloakRails::Curl.new
+    end
+
+    def fetch_tokens(email:, password:, otp_password: nil)
+      request = @curl.post(path: KeycloakRails.openid_config['token_endpoint'],
+                           headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                           body: { 'grant_type': 'password', 'client_id': KeycloakRails.client_id,
+                                   'client_secret': KeycloakRails.secret, 'username': email,
+                                   'password': password }.merge((otp_password ? { 'totp': otp_password } : {})))
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def fetch_tokens_by_handshake(code:, redirect_uri:)
+      request = @curl.post(path: KeycloakRails.openid_config['token_endpoint'],
+                           headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                           body: { 'grant_type': 'authorization_code', 'client_id': KeycloakRails.client_id,
+                                   'client_secret': KeycloakRails.secret, code: code,
+                                   "redirect_uri": redirect_uri })
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def fetch_current_user_info
+      request = @curl.post(path: KeycloakRails.openid_config['userinfo_endpoint'],
+                           headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                           body: { access_token: access_token })
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    def end_session(redirect_uri)
+      request = @curl.post(path: KeycloakRails.openid_config['end_session_endpoint'],
+                           headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                           body: { 'client_id': KeycloakRails.client_id,
+                                   'client_secret': KeycloakRails.secret,
+                                   'refresh_token': KeycloakRails.current_refresh_cookie,
+                                   'post_logout_redirect_uri': redirect_uri })
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+
+    # gets user sub by making an api call to auth server
+    def fetch_active_user_sub
+      fetch_current_user_info['sub']
+    end
+
+    # gets user sub by decoding the session_cookie
+    def decode_active_user_sub
+      decoded_access_token.first['sub']
+    end
+
+    def active_user_sub
+      return unless access_token
+      case KeycloakRails.decode_token_strategy
+      when :local then decode_active_user_sub
+      when :cloud then fetch_active_user_sub
+      end
+    end
+
+    # private
+
+    def access_token
+      KeycloakRails.currnet_session_cookie
+    end
+
+    def decoded_access_token
+      decode(access_token)
+    end
+
+    def decoded_refresh_token
+      decode(refresh_token)
+    end
+
+    def decode(token)
+      JWT.decode token, KeycloakRails.public_key, false, { algorithm: KeycloakRails.signature_algo }
+    end
+  end
+end

data/lib/keycloak_rails/version.rb

@@ -0,0 +1,3 @@
+module KeycloakRails
+  VERSION = '1.0.0-beta'
+end

data/lib/keycloak_rails.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# requires all dependencies
+require 'faraday'
+require 'jwt'
+require 'dry/configurable'
+
+# requires all modules and classes
+require 'keycloak_rails/version'
+require 'keycloak_rails/engine'
+require 'keycloak_rails/client'
+require 'keycloak_rails/user'
+require 'keycloak_rails/curl'
+require 'keycloak_rails/controller/helpers'
+require 'keycloak_rails/controller/magic_links'
+require 'keycloak_rails/controller/omniauth'
+require 'keycloak_rails/controller/passwords'
+require 'keycloak_rails/controller/registrations'
+require 'keycloak_rails/controller/sessions'
+require 'keycloak_rails/controller/unlocks'
+require 'app/models/keycloak_rails/sso'
+require 'app/models/keycloak_rails/concerns/sso_recipient'
+
+module KeycloakRails
+  extend Dry::Configurable
+
+  setting :sessions_controller, reader: true
+  setting :registrations_controller, reader: true
+  setting :unlocks_controller, reader: true
+  setting :passwords_controller, reader: true
+  setting :omniauth_controller, reader: true
+  setting :user_model, reader: true
+  setting :realm, reader: true
+  setting :public_key, reader: true
+  setting :auth_server_url, reader: true
+  setting :secret, reader: true
+  setting :client_id, reader: true
+  setting :decode_token_strategy, reader: true, default: :local
+  setting :signature_algo, reader: true
+  setting :allow_magic_links, reader: true, default: false
+
+  class << self
+    attr_accessor :session_cookie_proc, :destroy_session_cookie_proc, :refresh_cookie_proc, :destroy_refresh_cookie_proc
+
+    def currnet_session_cookie
+      session_cookie_proc.call
+    end
+
+    def current_refresh_cookie
+      refresh_cookie_proc.call
+    end
+
+    def destroy_auth_cookies
+      destroy_session_cookie_proc.call
+      destroy_refresh_cookie_proc.call
+    end
+
+    def openid_config
+      @openid_config ||= fetch_openid_configuration
+    end
+
+    def fetch_openid_configuration
+      request = Curl.new.get(path: "realms/#{realm}/.well-known/openid-configuration",
+                             headers: { 'Content-Type': 'application/x-www-form-urlencoded' })
+      raise StandardError, request[:response] unless request[:status] == :ok
+
+      request[:response]
+    end
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: keycloak_rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0.pre.beta
+platform: ruby
+authors:
+- Omar Luqman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+description: A rails wrapper for open source SSO project Keycloak.
+email:
+- oluqman@nucleushealthcare.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/app/models/keycloak_rails/concerns/sso_recipient.rb
+- lib/app/models/keycloak_rails/sso.rb
+- lib/generators/keycloak_rails/config/config_generator.rb
+- lib/generators/keycloak_rails/install/install_generator.rb
+- lib/generators/keycloak_rails/keycloak_rails.rb
+- lib/keycloak_rails.rb
+- lib/keycloak_rails/client.rb
+- lib/keycloak_rails/controller/helpers.rb
+- lib/keycloak_rails/controller/magic_links.rb
+- lib/keycloak_rails/controller/omniauth.rb
+- lib/keycloak_rails/controller/passwords.rb
+- lib/keycloak_rails/controller/registrations.rb
+- lib/keycloak_rails/controller/sessions.rb
+- lib/keycloak_rails/controller/unlocks.rb
+- lib/keycloak_rails/curl.rb
+- lib/keycloak_rails/engine.rb
+- lib/keycloak_rails/user.rb
+- lib/keycloak_rails/version.rb
+homepage: https://github.com/Laborocity/keycloak_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Laborocity/keycloak_rails
+  source_code_uri: https://github.com/Laborocity/keycloak_rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: "%q{API wrapper for Key Cloak SSO server.}"
+test_files: []