keycloak-admin 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c198fd53c7034b75c805c4479b73eec2dec2159da57e6cebd8056742ad40cd6
-  data.tar.gz: f2532b1773d60f633644bb5dd9c0c361933037db228ec871ac92aea73f4baf0b
+  metadata.gz: 9bc43409191a911c85de270b70021cbe48d0372844c5a2a4d87409f250d6b646
+  data.tar.gz: eee1d04d6026a04da64769c02cbe49ec9f84d186a1fafefc45476925979333c6
 SHA512:
-  metadata.gz: 553e781914529764e787e455918d878e7ce49902e4f75b679f66a6559d59a70684058f655e81f7de23bd3f83e9f884a26c3bad3a9d2c962600de66249176409a
-  data.tar.gz: 626a03f798614205ffe9218b76f31d8fd625810980c33f49d12ce322e79e5e47977104873863ea36b955b79efb68aa995af3f63efa4aad2beef77b38dba85527
+  metadata.gz: 96fccdf9c111acf6cfc67d6d05f7fd3b7e87140292d63df5dd9fdfebb228c30595416ae23ee8e465e06be1b54e3be857d8a64f599a447d642082086054805eb4
+  data.tar.gz: c49b8b8e7b2a13ae05eb69c47c3a0ee4c935a4e8a689fbf8863d01f843f95ee2506460e2ccf852223586266ae3591ee9cefff83819d087410b2fe53ccfadf0c1

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.2] - 2026-08-01
+
+* [Breaking] HTTP failures now raise a `KeycloakAdmin::ApiError` subclass instead of a bare `RuntimeError`. 
+  * Messages are unchanged, so code matching on the text keeps working. 
+  * Code rescuing `RuntimeError` explicitly must be updated. 
+  * A create call answering something other than `201 Created` now raises `KeycloakAdmin::UnexpectedResponseError`.
+* [Feature] A `401` answer now drops the cached access token and replays the request once with a freshly fetched one, so a token revoked before its advertised expiry no longer fails every call until it lapses.
+* [Fix] `GroupClient#members` called ActiveSupport's `Object#try` and raised `NoMethodError` outside a Rails application.
+* [Fix] `UserClient#execute_actions_email` (and `#forgot_password`) called ActiveSupport's `Numeric#seconds` and raised `NoMethodError` outside a Rails application whenever a `lifespan` was passed.
+* [Fix] `ClientAuthzPolicyClient#find_by` opened a second `?` in its URL, which folded `name`, `type`, `first` and `max` into the value of `permission`; Keycloak silently returned an unfiltered list.
+* [Fix] Query parameters are now percent-encoded everywhere they are built. Search terms, and the `redirect_uri` of `UserClient#execute_actions_email`, containing a space, `&` or `=` used to break the URL or forge extra parameters.
+* [Fix] `OrganizationClient#build` raised `NameError` instead of the intended `ArgumentError` when `domains` was not an `Array`.
+
+## [2.0.1] - 2026-07-31
+
+* [Feature] Requests are now logged through `config.logger` (method, URL, and response status) via Faraday's `:logger` middleware.
+* [Feature] The access token is now cached and reused (tracking `expires_in`) instead of being fetched before nearly every call. Previously, caching lived on the `Client` instance, but a fresh `Client` subclass is created for almost every call (e.g. `KeycloakAdmin.realm(x).users` builds a new `UserClient`), so the cache was rarely hit in practice; it now lives on the shared `Configuration`.
+* Publish the gem to RubyGems from Github Actions when a `v*` tag is pushed, using RubyGems' Trusted Publishing
+
 ## [2.0.0] - 2026-07-31
 
 * [Breaking] Replaced `rest-client` with `Faraday` as the underlying HTTP library. This should be transparent for callers of this gem's own API, but `config.rest_client_options` is renamed to `config.faraday_options` and its shape changes from rest-client's flat hash to Faraday's connection options (e.g. `{ timeout: 5 }` becomes `{ request: { timeout: 5 } }`, `{ verify_ssl: false }` becomes `{ ssl: { verify: false } }`). See the `Configuration` section of the README.

data/README.md

@@ -16,7 +16,7 @@ This gem *does not* require Rails.
 For example, using `bundle`, add this line to your Gemfile.
 
 ```ruby
-gem "keycloak-admin", "2.0.0"
+gem "keycloak-admin", "2.0.2"
 ```
 
 ## Login
@@ -109,6 +109,42 @@ All options have a default value. However, all of them can be changed in your in
 | `faraday_options` | `{}`| Hash | Optional | Options to pass to `Faraday.new` (e.g. `request:`, `ssl:`, `proxy:`) | `{ request: { timeout: 5 } }` | 
 
 
+## Error handling
+
+Every HTTP failure raises a `KeycloakAdmin::ApiError` carrying the `status`, `body` and `headers`
+of the response, so you never have to parse the message. Rescue as narrowly or as broadly as you need:
+
+```ruby
+begin
+  KeycloakAdmin.realm("a-realm").users.get(user_id)
+rescue KeycloakAdmin::NotFoundError => e   # exactly 404
+  nil
+rescue KeycloakAdmin::ClientError => e     # any 4xx
+  logger.warn("Rejected with #{e.status}: #{e.body}")
+  raise
+rescue KeycloakAdmin::ServerError => e     # any 5xx
+  raise
+end
+```
+
+| Class | Raised on |
+| ---- | ---- |
+| `KeycloakAdmin::Error` | Base class of every error this gem raises |
+| `KeycloakAdmin::ApiError` | Any non-2xx answer; parent of the two families below |
+| `KeycloakAdmin::ClientError` | Any 4xx |
+| `KeycloakAdmin::BadRequestError` | 400 |
+| `KeycloakAdmin::UnauthorizedError` | 401 |
+| `KeycloakAdmin::ForbiddenError` | 403 |
+| `KeycloakAdmin::NotFoundError` | 404 |
+| `KeycloakAdmin::ConflictError` | 409 |
+| `KeycloakAdmin::ServerError` | Any 5xx |
+| `KeycloakAdmin::UnexpectedResponseError` | A create call answered something other than `201 Created` |
+
+`Faraday::TimeoutError` and the other connection-level Faraday errors are left untouched and propagate as-is, since no response ever came back to describe.
+
+A `401` is handled before it reaches you: the cached access token is dropped and the request is replayed once with a freshly fetched one, so a token revoked before its advertised expiry does not fail every call until it lapses `KeycloakAdmin::UnauthorizedError` is raised only if the replay is
+refused too.
+
 ## Use Cases
 
 ### Supported features
@@ -348,7 +384,7 @@ KeycloakAdmin.realm("a_realm").groups.list
 
 Returns an array of `KeycloakAdmin::GroupRepresentation`.
 
-According to [the documentation](https://www.keycloak.org/docs-api/22.0.1/rest-api/index.html#_groups):
+According to [the documentation](https://www.keycloak.org/docs-api/22.0.2/rest-api/index.html#_groups):
 * When providing a `String` parameter, this produces an arbitrary search string
 * When providing a `Hash`, you can specify other fields (_e.g_ q, max, first)
 
@@ -885,3 +921,19 @@ From the `keycloak-admin-api` directory:
   $ docker build . -t keycloak-admin:test
   $ docker run -v `pwd`:/usr/src/app/ keycloak-admin:test rspec spec
 ```
+
+## How to release a new version
+
+Releases are published to [RubyGems](https://rubygems.org/gems/keycloak-admin) by GitHub Actions
+(`.github/workflows/release.yml`), through [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/):
+no API key is stored in this repository, the workflow exchanges a short-lived GitHub OIDC token for a
+scoped RubyGems credential.
+
+1. Update `KeycloakAdmin::VERSION` in `lib/keycloak-admin/version.rb` and the `CHANGELOG.md`
+2. Commit and push these changes to `main`
+3. Tag the commit and push the tag:
+
+```
+  $ git tag -a v2.0.2 -m "Version 2.0.2"
+  $ git push origin v2.0.2
+```

data/keycloak-admin.gemspec

@@ -12,14 +12,23 @@ Gem::Specification.new do |spec|
   spec.description = "Keycloak Admin REST API client written in Ruby"
   spec.license     = "MIT"
 
-  spec.files = `git ls-files -z`.split("\x0")
+  spec.files         = Dir.glob(["lib/**/*.rb", "CHANGELOG.md", "MIT-LICENSE", "README.md", "keycloak-admin.gemspec"]).sort
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = '>= 3.1'
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata = {
+    "source_code_uri"       => spec.homepage,
+    "changelog_uri"         => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri"       => "#{spec.homepage}/issues",
+    "rubygems_mfa_required" => "true"
+  }
 
   spec.add_dependency "http-cookie", "~> 1.0", ">= 1.0.3"
   spec.add_dependency "faraday", "~> 2.0"
   spec.add_dependency "base64"
-  spec.add_development_dependency "rspec",  "3.13.2"
-  spec.add_development_dependency "byebug", "12.0.0"
-end
+  spec.add_development_dependency "rspec",   "3.13.2"
+  spec.add_development_dependency "byebug",  "12.0.0"
+  spec.add_development_dependency "rake",    ">= 13.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+end

data/lib/keycloak-admin/client/client.rb

@@ -1,3 +1,5 @@
+require "uri"
+
 module KeycloakAdmin
   class Client
 
@@ -9,8 +11,11 @@ module KeycloakAdmin
       @configuration.server_url&.sub(/\/+\z/, "")
     end
 
+    # Cached on @configuration, not on this instance, since a new Client subclass is
+    # created for nearly every call (e.g. KeycloakAdmin.realm(x).users creates a fresh
+    # UserClient) - caching here alone would fetch a new token on almost every request.
     def current_token
-      @current_token ||= KeycloakAdmin.create_client(@configuration, @configuration.client_realm_name).token.get
+      @configuration.cached_token || @configuration.cache_token(fetch_token)
     end
 
     def headers
@@ -22,16 +27,24 @@ module KeycloakAdmin
     end
 
     def execute_http
-      yield
-    rescue Faraday::TimeoutError
-      raise
-    rescue Faraday::ClientError, Faraday::ServerError => e
-      http_error(e.response)
+      replayed = false
+      begin
+        yield
+      rescue Faraday::TimeoutError
+        raise
+      rescue Faraday::ClientError, Faraday::ServerError => e
+        if !replayed && e.response && e.response[:status] == 401 && !@configuration.cached_token.nil?
+          @configuration.clear_cached_token!
+          replayed = true
+          retry
+        end
+        raise ApiError.from_response(e.response)
+      end
     end
 
     def created_id(response)
       unless response.status == 201
-        raise "Create method returned status #{response.reason_phrase} (Code: #{response.status}); expected status: Created (201)"
+        raise UnexpectedResponseError.new(response.status, response.reason_phrase)
       end
       (_head, _separator, id) = response.headers[:location].rpartition("/")
       id
@@ -49,12 +62,18 @@ module KeycloakAdmin
 
     private
 
-    def resource(url)
-      Resource.new(url, @configuration.faraday_options)
+    def build_query(parameters)
+      parameters.map do |name, value|
+        "#{URI.encode_uri_component(name.to_s)}=#{URI.encode_uri_component(value.to_s)}"
+      end.join("&")
     end
 
-    def http_error(response)
-      raise "Keycloak: The request failed with response code #{response[:status]} and message: #{response[:body]}"
+    def fetch_token
+      KeycloakAdmin.create_client(@configuration, @configuration.client_realm_name).token.get
+    end
+
+    def resource(url)
+      Resource.new(url, @configuration.faraday_options, @configuration.logger)
     end
   end
 end

data/lib/keycloak-admin/client/client_authz_permission_client.rb

@@ -20,7 +20,7 @@ module KeycloakAdmin
 
     def find_by(name, resource_param, scope = nil)
       response = execute_http do
-        url = "#{authz_permission_url(@client_id)}?name=#{name}&resource=#{resource_param}&type=#{@type}&scope=#{scope}&deep=true&first=0&max=100"
+        url = "#{authz_permission_url(@client_id)}?#{build_query(name: name, resource: resource_param, type: @type, scope: scope, deep: true, first: 0, max: 100)}"
         resource(url).get(headers)
       end
       JSON.parse(response).map { |role_as_hash| ClientAuthzPermissionRepresentation.from_hash(role_as_hash) }

data/lib/keycloak-admin/client/client_authz_policy_client.rb

@@ -33,7 +33,7 @@ module KeycloakAdmin
 
     def find_by(name, type)
       response = execute_http do
-        url = "#{authz_policy_url(@client_id, @type)}?permission=false&name=#{name}&type=#{type}&first=0&max=11"
+        url = "#{authz_policy_url(@client_id, @type)}&#{build_query(name: name, type: type, first: 0, max: 11)}"
         resource(url).get(headers)
       end
       JSON.parse(response).map { |role_as_hash| ClientAuthzPolicyRepresentation.from_hash(role_as_hash) }

data/lib/keycloak-admin/client/client_authz_resource_client.rb

@@ -47,7 +47,7 @@ module KeycloakAdmin
 
     def find_by(name, type, uris, owner, scope)
       response = execute_http do
-        url = "#{authz_resources_url(@client_id)}?name=#{name}&type=#{type}&uris=#{uris}&owner=#{owner}&scope=#{scope}&deep=true&first=0&max=100"
+        url = "#{authz_resources_url(@client_id)}?#{build_query(name: name, type: type, uris: uris, owner: owner, scope: scope, deep: true, first: 0, max: 100)}"
         resource(url).get(headers)
       end
       JSON.parse(response).map { |role_as_hash| ClientAuthzResourceRepresentation.from_hash(role_as_hash) }

data/lib/keycloak-admin/client/client_authz_scope_client.rb

@@ -35,7 +35,7 @@ module KeycloakAdmin
     end
 
     def search(name)
-      url = "#{authz_scopes_url(@client_id)}?first=0&max=11&deep=false&name=#{name}"
+      url = "#{authz_scopes_url(@client_id)}?#{build_query(first: 0, max: 11, deep: false, name: name)}"
       response = execute_http do
         resource(url).get(headers)
       end

data/lib/keycloak-admin/client/configurable_token_client.rb

@@ -25,7 +25,8 @@ module KeycloakAdmin
               Authorization: "Bearer #{user_access_token}",
               content_type: :json,
               accept: :json
-            }
+            },
+            logger: @configuration.logger
           )
         )
       end

data/lib/keycloak-admin/client/group_client.rb

@@ -75,11 +75,8 @@ module KeycloakAdmin
 
     def members(group_id, first=0, max=100)
       url = "#{groups_url(group_id)}/members"
-      query = {first: first.try(:to_i), max: max.try(:to_i)}.compact
-      unless query.empty?
-        query_string = query.to_a.map { |e| "#{e[0]}=#{e[1]}" }.join("&")
-        url = "#{url}?#{query_string}"
-      end
+      query = {first: first&.to_i, max: max&.to_i}.compact
+      url = "#{url}?#{build_query(query)}" unless query.empty?
       response = execute_http do
         resource(url).get(headers)
       end
@@ -118,7 +115,8 @@ module KeycloakAdmin
             url: url,
             method: :delete,
             payload: create_payload([role_representation]),
-            headers: headers
+            headers: headers,
+            logger: @configuration.logger
           )
         )
       end

data/lib/keycloak-admin/client/organization_client.rb

@@ -170,24 +170,24 @@ module KeycloakAdmin
     end
 
     def count_url(exact, query, search)
-      query_parameters = {exact: exact, q: query, search: search}.compact.to_a.map { |e| "#{e[0]}=#{e[1]}" }.join("&")
+      query_parameters = build_query({exact: exact, q: query, search: search}.compact)
       "#{organizations_url}/count?#{query_parameters}"
     end
 
     def organizations_url_with_parameters(brief_representation, exact, first, max, query, search)
-      query_parameters = {
+      query_parameters = build_query({
         briefRepresentation: brief_representation,
         exact: exact,
         first: first,
         max: max,
         q: query,
         search: search
-      }.compact.to_a.map { |e| "#{e[0]}=#{e[1]}" }.join("&")
+      }.compact)
       "#{organizations_url}?#{query_parameters}"
     end
 
     def associated_with_member_url(member_id, brief_representation=true)
-      "#{organizations_url}/members/#{member_id}/organizations?briefRepresentation=#{brief_representation}"
+      "#{organizations_url}/members/#{member_id}/organizations?#{build_query(briefRepresentation: brief_representation)}"
     end
 
     def members_count_url(organization_id)
@@ -212,19 +212,19 @@ module KeycloakAdmin
     end
 
     def members_url_with_query_parameters(organization_id, exact, first, max, membership_type, search)
-      query_parameters = {
+      query_parameters = build_query({
         exact: exact,
         first: first,
         max: max,
         membershipType: membership_type,
         search: search
-      }.compact.to_a.map { |e| "#{e[0]}=#{e[1]}" }.join("&")
+      }.compact)
       "#{organization_url(organization_id)}/members?#{query_parameters}"
     end
 
     def build(name, alias_name, enabled, description, redirect_url=nil, domains=[], attributes={})
       unless domains.is_a?(Array)
-        raise ArgumentError.new("domains must be an Array, got #{new_domains.class}")
+        raise ArgumentError.new("domains must be an Array, got #{domains.class}")
       end
 
       unless domains.all? { |domain| domain.is_a?(KeycloakAdmin::OrganizationDomainRepresentation) }

data/lib/keycloak-admin/client/resource.rb

@@ -0,0 +1,98 @@
+require "faraday"
+require "uri"
+
+module KeycloakAdmin
+  # Thin facade over Faraday that mirrors RestClient::Resource/RestClient::Request's call
+  # shape, so every client class can build/send requests without depending on Faraday's API
+  # directly.
+  class Resource
+    MIME_TYPES = { json: "application/json" }.freeze
+
+    def self.execute(options)
+      options = options.dup
+      method  = options.delete(:method)
+      url     = options.delete(:url)
+      payload = options.delete(:payload)
+      headers = options.delete(:headers) || {}
+      logger  = options.delete(:logger)
+      new(url, options, logger).send(:request, method, payload, headers)
+    end
+
+    def self.put(url, payload, headers = {}, logger = nil)
+      new(url, {}, logger).put(payload, headers)
+    end
+
+    def initialize(url, options = {}, logger = nil)
+      @url     = url
+      @options = options || {}
+      @logger  = logger
+    end
+
+    def get(headers = {})
+      request(:get, nil, headers)
+    end
+
+    def delete(headers = {})
+      request(:delete, nil, headers)
+    end
+
+    def post(payload, headers = {})
+      request(:post, payload, headers)
+    end
+
+    def put(payload, headers = {})
+      request(:put, payload, headers)
+    end
+
+    private
+
+    def request(method, payload, headers)
+      headers      = headers || {}
+      query        = headers[:params]
+      send_headers = build_headers(headers.reject { |key, _| key == :params })
+      body         = encode_payload(payload)
+
+      # RestClient::Payload::UrlEncoded always stamped this Content-Type for Hash payloads,
+      # regardless of what the caller's headers said; token retrieval relies on it and never
+      # sets content_type itself.
+      if payload.is_a?(Hash) && !send_headers.key?("Content-Type")
+        send_headers["Content-Type"] = "application/x-www-form-urlencoded"
+      end
+
+      faraday_response = connection.public_send(method) do |req|
+        req.params.update(query) if query
+        send_headers.each { |name, value| req.headers[name] = value }
+        req.body = body unless body.nil?
+      end
+      Response.new(faraday_response)
+    end
+
+    def connection
+      Faraday.new(url: @url, **@options) do |f|
+        f.response :raise_error
+        # Added after :raise_error so it logs the raw response (status/duration) before
+        # :raise_error can raise, including on failures. Faraday's logger middleware logs
+        # headers by default, which would print the bearer token on every call; headers: false
+        # keeps this to method/url/status only. Bodies are already off by Faraday's own default.
+        f.response :logger, @logger, headers: false if @logger
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def encode_payload(payload)
+      return nil if payload.nil?
+      payload.is_a?(Hash) ? URI.encode_www_form(payload) : payload.to_s
+    end
+
+    def build_headers(headers)
+      headers.each_with_object({}) do |(key, value), result|
+        name         = key.is_a?(Symbol) ? humanize(key) : key.to_s
+        result[name] = value.is_a?(Symbol) ? MIME_TYPES.fetch(value, value.to_s) : value
+      end
+    end
+
+    def humanize(key)
+      key.to_s.split("_").map { |word| word.capitalize }.join("-")
+    end
+  end
+end

data/lib/keycloak-admin/client/response.rb

@@ -0,0 +1,36 @@
+module KeycloakAdmin
+  # Wraps a Faraday::Response the way RestClient::Response used to: as the body string
+  # itself (RestClient::Response < String), so existing call sites that do JSON.parse(response)
+  # or response.to_i keep working, while .body/.headers/.status/.code/.reason_phrase stay
+  # available for call sites that need response metadata.
+  class Response < String
+    attr_reader :status, :reason_phrase, :headers
+
+    def initialize(faraday_response)
+      super(faraday_response.body.to_s)
+      @status        = faraday_response.status
+      @reason_phrase = faraday_response.reason_phrase
+      @headers       = symbolize_headers(faraday_response.headers)
+    end
+
+    alias_method :code, :status
+    alias_method :body, :to_s
+
+    private
+
+    def symbolize_headers(faraday_headers)
+      faraday_headers.each_with_object({}) do |(key, value), result|
+        symbol_key         = key.downcase.tr("-", "_").to_sym
+        result[symbol_key] = symbol_key == :set_cookie ? split_set_cookie(value) : value
+      end
+    end
+
+    # Net::HTTP (used by Faraday's default adapter) joins repeated Set-Cookie header lines with
+    # ", " (see Net::HTTPHeader#each_header), losing the one-header-per-cookie structure RestClient
+    # exposed as an Array. Re-split on cookie boundaries rather than on every comma, since a comma
+    # can also appear inside a cookie's own "Expires=Wed, 09 Jun 2027 ..." attribute.
+    def split_set_cookie(value)
+      value.split(/,(?=\s*[^;\s]+=)/).map(&:strip)
+    end
+  end
+end

data/lib/keycloak-admin/client/role_mapper_client.rb

@@ -27,7 +27,8 @@ module KeycloakAdmin
             method: :delete,
             url: realm_level_url,
             payload: create_payload(role_representation_list),
-            headers: headers
+            headers: headers,
+            logger: @configuration.logger
           )
         )
       end

data/lib/keycloak-admin/client/user_client.rb

@@ -28,7 +28,8 @@ module KeycloakAdmin
           method: :put,
           url: users_url(user_id),
           payload: create_payload(user_representation_body),
-          headers: headers
+          headers: headers,
+          logger: @configuration.logger
         )
       )
     end
@@ -39,7 +40,8 @@ module KeycloakAdmin
           method: :put,
           url: "#{users_url(user_id)}/groups/#{group_id}",
           payload: create_payload({}),
-          headers: headers
+          headers: headers,
+          logger: @configuration.logger
         )
       )
     end
@@ -49,7 +51,8 @@ module KeycloakAdmin
         @configuration.faraday_options.merge(
           method: :delete,
           url: "#{users_url(user_id)}/groups/#{group_id}",
-          headers: headers
+          headers: headers,
+          logger: @configuration.logger
         )
       )
     end
@@ -116,7 +119,8 @@ module KeycloakAdmin
             method: :put,
             url: reset_password_url(user_id),
             payload: { type: "password", value: new_password, temporary: false }.to_json,
-            headers: headers
+            headers: headers,
+            logger: @configuration.logger
           )
         )
       end
@@ -137,10 +141,14 @@ module KeycloakAdmin
     def execute_actions_email(user_id, actions=[], lifespan=nil, redirect_uri=nil, client_id=nil)
       raise ArgumentError.new("client_id must be defined") if client_id.nil? && !redirect_uri.nil?
       execute_http do
-        lifespan_param = lifespan.nil? ? "" : "&lifespan=#{lifespan.seconds}"
-        redirect_uri_param = redirect_uri.nil? ? "" : "&redirect_uri=#{redirect_uri}"
-        client_id_param = client_id.nil? ? "" : "client_id=#{client_id}"
-        Resource.put("#{execute_actions_email_url(user_id)}?#{client_id_param}#{redirect_uri_param}#{lifespan_param}", create_payload(actions), headers)
+        query = {}
+        query[:client_id]    = client_id     unless client_id.nil?
+        query[:redirect_uri] = redirect_uri  unless redirect_uri.nil?
+        query[:lifespan]     = lifespan.to_i unless lifespan.nil?
+
+        url = execute_actions_email_url(user_id)
+        url = "#{url}?#{build_query(query)}" unless query.empty?
+        Resource.put(url, create_payload(actions), headers, @configuration.logger)
       end
       user_id
     end
@@ -153,7 +161,8 @@ module KeycloakAdmin
             method: :post,
             url: impersonation.impersonation_url,
             payload: impersonation.body.to_json,
-            headers: impersonation.headers
+            headers: impersonation.headers,
+            logger: @configuration.logger
           )
         )
       end
@@ -177,7 +186,8 @@ module KeycloakAdmin
           @configuration.faraday_options.merge(
             method: :post,
             url: logout_url(user_id),
-            headers: headers
+            headers: headers,
+            logger: @configuration.logger
           )
         )
       end
@@ -200,7 +210,8 @@ module KeycloakAdmin
             method: :post,
             url: federated_identity_url(user_id, idp_id),
             payload: fed_id_rep.to_json,
-            headers: headers
+            headers: headers,
+            logger: @configuration.logger
           )
         )
       end

data/lib/keycloak-admin/configuration.rb

@@ -4,6 +4,28 @@ module KeycloakAdmin
   class Configuration
     attr_accessor :server_url, :server_domain, :client_id, :client_secret, :client_realm_name, :use_service_account, :username, :password, :logger, :faraday_options
 
+    # Treat a cached token as expired this many seconds before its real expiry, so it
+    # cannot go stale between the check below and the request that relies on it.
+    TOKEN_EXPIRY_SAFETY_MARGIN_SECONDS = 10
+
+    # Returns the cached TokenRepresentation, or nil if there is none or it is (about to be) expired.
+    def cached_token
+      return nil if @token_expires_at.nil? || Time.now >= @token_expires_at
+      @cached_token
+    end
+
+    def cache_token(token_representation)
+      return token_representation unless token_representation.expires_in.is_a?(Numeric)
+      @cached_token     = token_representation
+      @token_expires_at = Time.now + token_representation.expires_in - TOKEN_EXPIRY_SAFETY_MARGIN_SECONDS
+      token_representation
+    end
+
+    def clear_cached_token!
+      @cached_token     = nil
+      @token_expires_at = nil
+    end
+
     def body_for_token_retrieval
       if use_service_account
         body_for_service_account