ruby-keycloak-admin 26.0.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e0ce0221f1b819d51a1b15b34e9c143f5200df7dbfb470f078e75d971c53792
+  data.tar.gz: ab7bfe86c2b7967661c9f0df6f7ca3deb7d894ff73bfdee7df74dd6c1a89583f
+SHA512:
+  metadata.gz: 292f27418bf59e5db36b15b476a4a666c4cc4c68ff0685e2b22555fb3a3931ec25d194993169c98e4cfe17c0a78196e6584befa9c2bf89bd88d8b53be28ae76f
+  data.tar.gz: 815897d5d7ce17ecd3d84ca7602fc135f905e610f44d6347fca0802d11e96532245066884697586472145163ca63205b0ea01b04fc1c4f515aee0de2b8b5cb42

data/lib/keycloak/admin/agent.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'time'
+
+require 'keycloak/admin/error'
+
+module Keycloak
+  module Admin
+    class Agent # :nodoc: all
+      include HTTParty
+      headers 'Accept' => 'application/json', 'Content-Type' => 'application/json'
+      debug_output $stdout if ENV['KEYCLOAK_ADMIN_DEBUG']
+
+      attr_accessor :base_url, :username, :password, :realm, :grant_type, :always_terminate
+
+      def initialize
+        @base_url = 'http://localhost:8080'
+        @realm = 'master'
+        @username = 'nil'
+        @password = 'nil'
+        @grant_type = 'password'
+        @always_terminate = false
+      end
+
+      def logout
+        terminate_session
+      end
+
+      %i[get post put delete head].each do |method|
+        define_method method do |path, params: {}|
+          request(method, path, params:)
+        end
+      end
+
+      def request(method, path, params: {})
+        refresh_session || create_session
+
+        params[:headers] ||= {}
+        params[:headers][:Authorization] = "Bearer #{@session['access_token']}"
+
+        response = self.class.send(
+          method,
+          "#{@base_url}/#{path}",
+          body: params[:body],
+          headers: params[:headers]
+        )
+
+        terminate_session if @always_terminate
+
+        Keycloak::Admin.raise_error(response) if !response.code.between?(200, 299)
+
+        response.parsed_response
+      end
+
+      private
+
+      def create_session
+        return false if !session_expired?
+
+        response = self.class.post(
+          "#{@base_url}/realms/master/protocol/openid-connect/token",
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: {
+            grant_type: 'password',
+            client_id: 'admin-cli',
+            username: @username,
+            password: @password
+          }
+        )
+
+        Keycloak::Admin.raise_error(response) if !response.code.between?(200, 299)
+
+        store_session(response)
+
+        true
+      end
+
+      def refresh_session
+        return false if !session_running?
+        return false if refresh_expired?
+
+        response = self.class.post(
+          "#{@base_url}/realms/master/protocol/openid-connect/token",
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: {
+            grant_type: 'refresh_token',
+            client_id: 'admin-cli',
+            refresh_token: @session['refresh_token']
+          }
+        )
+
+        return false if response.code.eql?(400)
+        return Keycloak::Admin.raise_error(response) if !response.code.between?(200, 299)
+
+        store_session(response)
+
+        true
+      end
+
+      def terminate_session
+        return false if !session_running?
+        return false if refresh_expired?
+
+        response = self.class.post(
+          "#{@base_url}/realms/master/protocol/openid-connect/logout",
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: {
+            client_id: 'admin-cli',
+            refresh_token: @session['refresh_token']
+          }
+        )
+
+        @session = nil
+
+        Keycloak::Admin.raise_error(response) if !response.code.between?(200, 299)
+
+        true
+      end
+
+      def store_session(response)
+        @session = response.parsed_response
+        @session['expires_at'] = Time.now + @session['expires_in']
+        @session['refresh_expires_at'] = Time.now + @session['refresh_expires_in']
+      end
+
+      def session_running?
+        !@session.nil?
+      end
+
+      def session_expired?
+        return true if @session.nil?
+
+        Time.now > @session['expires_at']
+      end
+
+      def refresh_expired?
+        return true if @session.nil?
+
+        Time.now > @session['refresh_expires_at']
+      end
+    end
+  end
+end

data/lib/keycloak/admin/clients.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'keycloak/admin/resource'
+
+module Keycloak
+  module Admin
+    ##
+    # Clients resource.
+    #
+    # The class is based on Keycloak::Admin::Resource and
+    # Keycloak::Admin::Resource::Pagination.
+    module Clients
+      class << self
+        include Keycloak::Admin::Resource
+
+        private
+
+        def resource
+          "admin/realms/#{@agent.realm}/clients"
+        end
+      end
+    end
+  end
+end

data/lib/keycloak/admin/error.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Keycloak
+  module Admin
+    class ConfigurationError < StandardError; end # :nodoc:
+    class ConnectionFailedError < StandardError; end # :nodoc:
+    class NotFoundError < StandardError; end # :nodoc:
+    class UnauthorizedError < StandardError; end # :nodoc:
+    class ForbiddenError < StandardError; end # :nodoc:
+    class BadRequestError < StandardError; end # :nodoc:
+    class ConflictError < StandardError; end # :nodoc:
+    class InternalServerError < StandardError; end # :nodoc:
+    class ServiceUnavailableError < StandardError; end # :nodoc:
+    class MethodNotAllowedError < StandardError; end # :nodoc:
+    class BadGatewayError < StandardError; end # :nodoc:
+
+    class << self
+      def raise_error(response)
+        error_classes = {
+          400 => BadRequestError,
+          401 => UnauthorizedError,
+          403 => ForbiddenError,
+          404 => NotFoundError,
+          405 => MethodNotAllowedError,
+          409 => ConflictError,
+          500 => InternalServerError,
+          502 => BadGatewayError,
+          503 => ServiceUnavailableError
+        }
+        error_class = error_classes[response.code] || StandardError
+
+        raise error_class, error_message(response)
+      end
+
+      private
+
+      def error_message(response)
+        parsed_response = response.parsed_response
+
+        return parsed_response if response.parsed_response.is_a?(String)
+
+        if response.parsed_response.is_a?(Hash)
+          return parsed_response['errorMessage'] ||
+                 parsed_response['error'] ||
+                 'Unknown error'
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/keycloak/admin/groups.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'keycloak/admin/resource'
+require 'keycloak/admin/resource/pagination'
+
+module Keycloak
+  module Admin
+    ##
+    # Groups resource.
+    #
+    # The class is based on Keycloak::Admin::Resource and
+    # Keycloak::Admin::Resource::Pagination. It provides following
+    # additional methods:
+    #
+    # * ::add
+    # * ::remove
+    # * ::members
+    module Groups
+      class << self
+        include Keycloak::Admin::Resource
+        include Keycloak::Admin::Resource::Pagination
+
+        ##
+        # Add user to group.
+        def add(id, user_id)
+          @agent.put("/admin/realms/#{@agent.realm}/users/#{user_id}/groups/#{id}")
+
+          true
+        end
+
+        ##
+        # Remove user from group.
+        def remove(id, user_id)
+          @agent.delete("/admin/realms/#{@agent.realm}/users/#{user_id}/groups/#{id}")
+
+          true
+        end
+
+        ##
+        # Get group members.
+        def members(id)
+          objects = []
+          (1..pages).each do |page|
+            first = (page * MAX_ENTRIES) - MAX_ENTRIES
+            objects << @agent.get("#{resource}/#{id}/members?first=#{first}&max=#{MAX_ENTRIES}")
+          end
+
+          objects.flatten.map { |object| mash(object) }
+        end
+
+        ##
+        # Create subgroup.
+        def subgroup(id, attributes)
+          @agent.post("#{resource}/#{id}/children", params: { body: attributes.to_json })
+
+          true
+        end
+
+        private
+
+        def resource
+          "admin/realms/#{@agent.realm}/groups"
+        end
+      end
+    end
+  end
+end

data/lib/keycloak/admin/realms.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'keycloak/admin/resource'
+
+module Keycloak
+  module Admin
+    ##
+    # Realms resource.
+    #
+    # The class is based on Keycloak::Admin::Resource and
+    # Keycloak::Admin::Resource::Pagination. The method #find_by_id is renamed
+    # to +find_by_name+.
+    module Realms
+      class << self
+        include Keycloak::Admin::Resource
+        if method_defined? :find_by_id
+          alias find_by_name find_by_id
+          undef find_by_id
+        end
+
+        private
+
+        def resource
+          '/admin/realms'
+        end
+      end
+    end
+  end
+end

data/lib/keycloak/admin/resource/pagination.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Keycloak
+  module Admin
+    module Resource
+      ##
+      # Abstract class extension for Keycloak::Admin resources with methods
+      # providing pagination.
+      #
+      # * #all
+      module Pagination
+        MAX_ENTRIES = 100
+
+        ##
+        # List all resources.
+        def all
+          objects = []
+          (1..pages).each do |page|
+            first = (page * MAX_ENTRIES) - MAX_ENTRIES
+            objects << @agent.get("#{resource}?first=#{first}&max=#{MAX_ENTRIES}")
+          end
+
+          objects.flatten.map { |object| mash(object) }
+        end
+
+        private
+
+        def count
+          @agent.get("#{resource}/count")
+        end
+
+        def pages
+          count = count()
+          count = count['count'] if count.is_a?(Hash)
+
+          return 0 if count.zero?
+          return 1 if count <= MAX_ENTRIES
+
+          pages = count / MAX_ENTRIES
+          pages += 1 if (count % MAX_ENTRIES).positive?
+
+          pages
+        end
+      end
+    end
+  end
+end

data/lib/keycloak/admin/resource.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'hashie'
+
+module Keycloak
+  module Admin
+    ##
+    # Abstract class for Keycloak::Admin resources with common methods.
+    #
+    # * #all
+    # * #create
+    # * #count
+    # * #delete
+    # * #find_by, alias #lookup
+    # * #find_by_id, alias #get
+    # * #update, alias #edit
+    module Resource
+      attr_writer :agent
+
+      ##
+      # List all resource objects.
+      def all
+        objects = @agent.get(resource)
+
+        objects.map { |object| mash(object) }
+      end
+
+      ##
+      # Create a new resource object.
+      def create(attributes)
+        @agent.post(resource, params: { body: attributes.to_json })
+
+        true
+      end
+
+      ##
+      # Delete a resource object by id.
+      def delete(id)
+        @agent.delete("#{resource}/#{id}")
+
+        true
+      end
+
+      ##
+      # Find resource objects by attributes, name and value.
+      def find_by(lookup)
+        objects = all
+
+        lookup.each do |key, value|
+          objects = objects.select do |object|
+            match_value?(object, key, value)
+          end
+          break if !objects
+        end
+
+        objects || []
+      end
+      alias lookup find_by
+
+      ##
+      # Find a resource object by id.
+      def find_by_id(id)
+        object = @agent.get("#{resource}/#{id}")
+
+        mash(object)
+      end
+      alias get find_by_id
+
+      ##
+      # Update a resource object by id.
+      def update(id, attributes)
+        @agent.put("#{resource}/#{id}", params: { body: attributes.to_json })
+
+        true
+      end
+      alias edit update
+
+      private
+
+      def resource
+        raise NotImplementedError
+      end
+
+      def match_value?(object, key, value)
+        return false if !object.key?(key)
+
+        if value.is_a?(String)
+          object[key].match?(value)
+        else
+          object[key] == value
+        end
+      end
+
+      def mash(object)
+        if object.is_a?(Array)
+          object.map { |item| Hashie::Mash.new(item) }
+        else
+          Hashie::Mash.new(object)
+        end
+      end
+    end
+  end
+end

data/lib/keycloak/admin/users.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'keycloak/admin/resource'
+require 'keycloak/admin/resource/pagination'
+
+module Keycloak
+  module Admin
+    ##
+    # Users resource.
+    #
+    # The class is based on Keycloak::Admin::Resource and
+    # Keycloak::Admin::Resource::Pagination. It provides following
+    # additional methods:
+    #
+    # * ::join
+    # * ::leave
+    # * ::logout
+    # * ::password
+    # * ::sessions
+    module Users
+      class << self
+        include Keycloak::Admin::Resource
+        include Keycloak::Admin::Resource::Pagination
+
+        ##
+        # Add user to group.
+        def join(id, group_id)
+          @agent.put("#{resource}/#{id}/groups/#{group_id}")
+
+          true
+        end
+
+        ##
+        # Remove user from group.
+        def leave(id, group_id)
+          @agent.delete("#{resource}/#{id}/groups/#{group_id}")
+
+          true
+        end
+
+        ##
+        # User membership.
+        def membership(id)
+          objects = []
+          (1..pages).each do |page|
+            first = (page * MAX_ENTRIES) - MAX_ENTRIES
+            objects << @agent.get("#{resource}/#{id}/groups?first=#{first}&max=#{MAX_ENTRIES}")
+          end
+
+          objects.flatten.map { |object| mash(object) }
+        end
+
+        ##
+        # Logout user from all sessions.
+        def logout(id)
+          @agent.post("#{resource}/#{id}/logout")
+
+          true
+        end
+
+        ##
+        # Set new password for user.
+        def password(id, attributes)
+          # { temporary: false, value: 'password' }
+          attributes[:type] = 'password'
+          @agent.put("#{resource}/#{id}/reset-password", params: { body: attributes.to_json })
+
+          true
+        end
+
+        ##
+        # Get user sessions.
+        def sessions(id)
+          objects = @agent.get("#{resource}/#{id}/sessions")
+
+          objects.map { |object| mash(object) }
+        end
+
+        private
+
+        def resource
+          "admin/realms/#{@agent.realm}/users"
+        end
+      end
+    end
+  end
+end

data/lib/keycloak/admin/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Keycloak
+  module Admin
+    VERSION = '26.0.8'
+  end
+end

data/lib/keycloak/admin.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'keycloak/admin/version'
+require 'keycloak/admin/agent'
+require 'keycloak/admin/error'
+
+require 'keycloak/admin/realms'
+require 'keycloak/admin/clients'
+require 'keycloak/admin/users'
+require 'keycloak/admin/groups'
+
+module Keycloak
+  ##
+  # Keycloak::Admin is a Ruby client for the Keycloak administration API.
+  #
+  # This is the main module. It provides methods to configure the connection to
+  # any Keycloak service, as well as methods to manage and control the several
+  # Keycloak resources.
+  module Admin
+    class << self
+      ##
+      # Configure Keycloak::Admin, the handler for all administration tasks.
+      #
+      # Provide Keycloak server base *url*, master realm admin user
+      # *credentials* and id of *realm* to be managed.
+      #
+      #   Keycloak::Admin.configure do |config|
+      #     config.username   = 'admin',
+      #     config.password   = 'admin',
+      #     config.realm      = 'zone',                         # default: master
+      #     config.base_url   = 'https://keycloak.example.com'  # default: http://localhost:8080
+      #   end
+      def configure
+        @agent ||= Keycloak::Admin::Agent.new
+        yield @agent
+        @configured = true
+
+        true
+      end
+
+      ##
+      # Verify if Keycloak::Admin is configured.
+      def configured?
+        @configured.nil? ? false : @configured
+      end
+
+      ##
+      # Raise error if Keycloak::Admin is not configured.
+      def configured!
+        raise Keycloak::Admin::ConfigurationError, 'Keycloak::Admin is not configured' if !configured?
+
+        true
+      end
+
+      ##
+      # Reset Keycloak::Admin configuration.
+      def reset!
+        @agent&.logout
+        @agent = nil
+        @configured = nil
+      end
+
+      ##
+      # Manage server realms. See Keycloak::Admin::Realms for usage.
+      def realms
+        configured!
+        Keycloak::Admin::Realms.agent = @agent
+
+        Keycloak::Admin::Realms
+      end
+
+      ##
+      # Manage realm clients. See Keycloak::Admin::Clients for usage.
+      def clients
+        configured!
+        Keycloak::Admin::Clients.agent = @agent
+
+        Keycloak::Admin::Clients
+      end
+
+      ##
+      # Manage realm users. See Keycloak::Admin::Users for usage.
+      def users
+        configured!
+        Keycloak::Admin::Users.agent = @agent
+
+        Keycloak::Admin::Users
+      end
+
+      ##
+      # Manage realm groups. See Keycloak::Admin::Groups for usage.
+      def groups
+        configured!
+        Keycloak::Admin::Groups.agent = @agent
+
+        Keycloak::Admin::Groups
+      end
+
+      ##
+      # Verify if the Keycloak server is ready.
+      #
+      # Beware, method returns +nil+ if the server does not respond (404 not
+      # found) to health checks.
+      def ready?
+        configured!
+
+        begin
+          @agent.head('health/ready')
+          true
+        rescue Keycloak::Admin::NotFoundError
+          nil
+        rescue Keycloak::Admin::ServiceUnavailableError
+          false
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: ruby-keycloak-admin
+version: !ruby/object:Gem::Version
+  version: 26.0.8
+platform: ruby
+authors:
+- Tobias Schäfer
+bindir: bin
+cert_chain: []
+date: 2025-01-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+description: |+
+  Ruby Keycloack admin API wrapper.
+
+  This gem provides a simple wrapper for the Keycloak admin API.
+
+    * https://www.keycloak.org
+    * https://www.keycloak.org/documentation
+    * https://www.keycloak.org/docs-api/26.0.8/rest-api/index.html
+
+email:
+- github@blackox.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/keycloak/admin.rb
+- lib/keycloak/admin/agent.rb
+- lib/keycloak/admin/clients.rb
+- lib/keycloak/admin/error.rb
+- lib/keycloak/admin/groups.rb
+- lib/keycloak/admin/realms.rb
+- lib/keycloak/admin/resource.rb
+- lib/keycloak/admin/resource/pagination.rb
+- lib/keycloak/admin/users.rb
+- lib/keycloak/admin/version.rb
+homepage: https://github.com/tschaefer/keycloak-admin
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/tschaefer/keycloak-admin
+  bug_tracker_uri: https://github.com/tschaefer/keycloak-admin/issues
+post_install_message: All your Keycloak are belong to us!
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Ruby Keycloack admin API wrapper.
+test_files: []
+...