keycloak-admin 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bc43409191a911c85de270b70021cbe48d0372844c5a2a4d87409f250d6b646
-  data.tar.gz: eee1d04d6026a04da64769c02cbe49ec9f84d186a1fafefc45476925979333c6
+  metadata.gz: c5abdd787b09a456ad094161dd8d61d1908937d1461086481059ae40cc064eea
+  data.tar.gz: f01144dcf8ab3e193f22644e979c36a88f7cd9738bc98cda7465a88c3d05d3c7
 SHA512:
-  metadata.gz: 96fccdf9c111acf6cfc67d6d05f7fd3b7e87140292d63df5dd9fdfebb228c30595416ae23ee8e465e06be1b54e3be857d8a64f599a447d642082086054805eb4
-  data.tar.gz: c49b8b8e7b2a13ae05eb69c47c3a0ee4c935a4e8a689fbf8863d01f843f95ee2506460e2ccf852223586266ae3591ee9cefff83819d087410b2fe53ccfadf0c1
+  metadata.gz: 250bf4f4bc7471eee8c96d7b84c413ab608ef0c35b1dfebb301f8838c674ebeed93ec571bf918d3b3837543067d3c151cc3acdf992cbe390da36bf4e761b2570
+  data.tar.gz: edcec9055546f2d8ee9a756e2f9fce7a5f29feb8ffc87ce452a98e8f5b554055b1e8dd03df03f6459a93592bf79a6c1d961acb31468db371d395e49f360d6144

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.3] - 2026-08-03
+
+* [Performance] Added `# frozen_string_literal: true` across all Ruby files to significantly reduce string object allocations and lower memory consumption.
+* [Performance] Refactored `Representation` JSON serialization (`as_json` and `to_json`) to eliminate intermediate Array and Hash allocations, improving CPU performance and memory footprint.
+* [Fix] `Representation#as_json` now strips `nil` values when generating JSON payloads. This fixes `HTTP 400 Bad Request` errors caused by strict API requirements in Keycloak 19+ (such as refusing `null` for `subGroupCount` and other restricted fields).
+* [Chore] Expanded the integration test suite to cover 100% of the REST clients against live Keycloak instances.
+* [Chore] Fixed the integration test suite against Keycloak 25 and 26. The `dummy` realm now enables internationalization and unmanaged user attributes, both required since Keycloak 24 for `locale` and custom attributes to be persisted; authorization permissions are deleted before the policy they depend on, since Keycloak 25 cascades that deletion; and permissions are asserted by name rather than by total count, which Keycloak 25 inflates with a seeded `Default Permission`. Each integration spec now loads the integration helper itself, instead of relying on another spec file having loaded it first.
+* [Fix] `Configuration#inspect` no longer renders `client_secret`, `password` or the cached access token, showing `[FILTERED]` instead. The default `#inspect` printed every attribute, so these credentials travelled into console sessions, `pp` output, and whatever local-variable dump an exception reporter attaches to a crash. A credential that is not set still renders as `nil`, so an inspect stays useful when authentication misbehaves.
+* [Fix] The access token cache introduced in 2.0.1 is now thread-safe.
+* [Fix] Identifiers are now percent-encoded before being interpolated into a URL path.
+* [Feature] `UserClient#update_password` accepts an optional `temporary:` keyword.
+* [Performance] `ClientClient#find_by_client_id` now has Keycloak filter with `?clientId=` instead of listing every client of the realm and comparing in Ruby
+* [Feature] `UserClient#list` and `GroupClient#list` accept optional `first:` and `max:` keywords. Keycloak answers `GET /users` with at most 100 entries when `max` is absent, so `users.list` silently returned a truncated realm with no way to ask for more; `GET /groups` applies no such cap, but both endpoints now page the same way. Calling either `list` with no argument sends no query parameter and is unchanged. `GroupClient#list` pairs a lone `max` with `first=0`, because Keycloak 19 only paginates that endpoint when both bounds are present and ignores `max` on its own; this is a no-op from Keycloak 23 on. Verified against live Keycloak 19.0, 23.0 and 26.7.0.
+* [Feature] `config.faraday_adapter` selects the Faraday adapter requests run through.
+* [Fix] `UserClient#impersonate` now takes part in the `401` replay introduced in 2.0.2. It called `get_redirect_impersonation` outside `execute_http`, so its `Authorization` header was built before the replay cleared the cached token: the second attempt resent the very bearer that had just been rejected and failed with the same `401`. It was the last call in the gem where the replay was inert.
+* [Fix] `CamelJson#camelize` no longer raises `NoMethodError` on an empty word.
+* [Fix] Query parameters built from an Array are now rendered as the key repeated once per element, instead of the array's Ruby `inspect` form: a list value used to be sent as `name=%5B%22a%22%2C%20%22b%22%5D`. An empty array now contributes no parameter at all; a `nil` still renders as `name=`, unchanged.
+* [Breaking] `ClientAuthzResourceClient#update` now replaces the submitted `uris` and `scopes` instead of merging them with the ones already stored. It used to union both, so updating twice with the same uri accumulated duplicates and no uri or scope could ever be removed. A key absent from the submitted hash still leaves the stored value untouched; presence is now what decides, not truthiness, so `uris: []` clears the uris and `owner_managed_access: false` is honoured rather than read as "not submitted". The method also no longer raises a bare `RuntimeError` when a scope has no `:name`, but a `KeycloakAdmin`-consistent `ArgumentError`, and no longer raises `TypeError` when the stored resource has no `uris` at all.
+* [Fix] `ClientRepresentation.from_hash` no longer produces wrongly typed defaults when the payload omits a field.
+* [Fix] `RoleRepresentation` and `SessionRepresentation` no longer define spurious `from_hash` and `from_hash=` instance accessors. A trailing comma after the last symbol of their `attr_accessor` list continued the argument list into the following `def`, which evaluates to a Symbol, so `attr_accessor` also received `:from_hash`. The class method `self.from_hash` was never shadowed, so parsing was unaffected.
+
+* [Fix] `UserClient#update`, `#add_group` and `#remove_group` built their request outside `execute_http`. They were the only methods on this client that raised a bare `Faraday::Error` instead of the documented `KeycloakAdmin::ApiError` hierarchy, and the only ones that did not replay a request rejected on a stale `401`.
+* [Fix] `UserClient#create!` could return a different user than the one it had just created. It looked the new user up with `search(email)`, and Keycloak's `search` parameter matches a *substring* of the username, email, first name or last name: creating `pioupioux@email.com` while `vieuxpioupioux@email.com` already existed returned the pre-existing account. The new user's id is now read from the `Location` header of the creation response, like `GroupClient#create!` already did. Two consequences: a creation not answered with `201 Created` now raises `KeycloakAdmin::UnexpectedResponseError` instead of returning `nil`, and the returned representation is fetched by id.
+* [Fix] `UserClient#create!` wrote the `locale` into the very `attributes` hash it was given, mutating the caller's object.
+* [Fix] `UserClient#execute_actions_email` (and `#forgot_password`) ignored `config.faraday_options`. It was the only call in the gem running with no timeout, and any configured SSL or proxy setting was silently dropped. The internal `KeycloakAdmin::Resource.put` shorthand it relied on is removed; its signature could not carry connection options.
+* [Chore] Migrated test suites to use WebMock `stub_request` instead of stubbing `KeycloakAdmin::Resource` directly, ensuring tests validate the actual network payload.
+
 ## [2.0.2] - 2026-08-01
 
 * [Breaking] HTTP failures now raise a `KeycloakAdmin::ApiError` subclass instead of a bare `RuntimeError`. 

data/MIT-LICENSE

@@ -1,20 +1,21 @@
-Copyright 2018 
+MIT License
 
-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:
+Copyright (c) 2026 Lorent Lempereur
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+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 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.
+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

@@ -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.2"
+gem "keycloak-admin", "2.0.3"
 ```
 
 ## Login
@@ -107,6 +107,30 @@ All options have a default value. However, all of them can be changed in your in
 | `password` | `nil`| String | Optional | Clear password to access the Admin REST API. Recommended if `user_service_account` is set to `false`. | `bobby` |
 | `logger` | `Logger.new(STDOUT)`| Logger | Optional | The logger used by `keycloak-admin` | `Rails.logger` | 
 | `faraday_options` | `{}`| Hash | Optional | Options to pass to `Faraday.new` (e.g. `request:`, `ssl:`, `proxy:`) | `{ request: { timeout: 5 } }` | 
+| `faraday_adapter` | `nil`| Symbol or Array | Optional | Faraday adapter to run requests through. `nil` uses `Faraday.default_adapter`. See _Connection reuse_ below. | `:net_http_persistent` |
+
+### Connection reuse
+
+By default this gem runs on `Faraday.default_adapter` (`net_http`), which wraps every request in `Net::HTTP#start`: the TCP connection is opened and closed again for each call. On a loop of admin calls, that handshake dominates the time spent.
+
+Set `faraday_adapter` to a pooling adapter to keep connections alive between calls. The adapter is not bundled, so add its gem to your own `Gemfile` alongside this one:
+
+```ruby
+# Gemfile
+gem "faraday-net_http_persistent"
+```
+
+```ruby
+KeycloakAdmin.configure do |config|
+  config.faraday_adapter = :net_http_persistent
+end
+```
+
+An adapter needing arguments is given as an array, splatted into Faraday's `adapter` call:
+
+```ruby
+config.faraday_adapter = [:net_http_persistent, { pool_size: 5 }]
+```
 
 
 ## Error handling
@@ -224,6 +248,13 @@ Returns an array of `KeycloakAdmin::UserRepresentation`.
 KeycloakAdmin.realm("a_realm").users.list
 ```
 
+Keycloak answers this endpoint with **at most 100 users** unless told otherwise, so a bare `list` silently truncates a larger realm. Pass `max` (and `first` to walk the pages) to go past it:
+
+```ruby
+KeycloakAdmin.realm("a_realm").users.list(max: 500)
+KeycloakAdmin.realm("a_realm").users.list(first: 100, max: 100)
+```
+
 ### Save a user
 
 Returns the provided `user`, which must be of type `KeycloakAdmin::UserRepresentation`.
@@ -274,6 +305,14 @@ new_password = "coco"
 KeycloakAdmin.realm("a_realm").users.update_password(user_id, new_password)
 ```
 
+Pass `temporary: true` to force the user to choose a new password at their next login. Keycloak
+records this as an `UPDATE_PASSWORD` required action on the account; a later permanent reset
+clears it.
+
+```ruby
+KeycloakAdmin.realm("a_realm").users.update_password(user_id, new_password, temporary: true)
+```
+
 ### List credentials
 
 ```ruby
@@ -380,11 +419,17 @@ Returns an array of `KeycloakAdmin::GroupRepresentation`.
 KeycloakAdmin.realm("a_realm").groups.list
 ```
 
+This endpoint applies no default cap, so a bare `list` already returns every group. `first` and `max` are still accepted, to page through a realm holding a lot of them:
+
+```ruby
+KeycloakAdmin.realm("a_realm").groups.list(first: 0, max: 100)
+```
+
 ### Search for a group
 
 Returns an array of `KeycloakAdmin::GroupRepresentation`.
 
-According to [the documentation](https://www.keycloak.org/docs-api/22.0.2/rest-api/index.html#_groups):
+According to [the documentation](https://www.keycloak.org/docs-api/latest/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)
 
@@ -915,7 +960,23 @@ KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).de
 
 ## How to execute library tests
 
-From the `keycloak-admin-api` directory:
+Unit tests need nothing but the gems:
+
+```
+  $ bundle install
+  $ bundle exec rake spec
+```
+
+Integration tests run against a real Keycloak. `docker-compose.yml` boots one configured like the one CI uses, so a green run locally means the same thing as a green run in CI:
+
+```
+  $ docker compose up -d
+  $ bundle exec rake integration
+```
+
+To reproduce a failure specific to an older Keycloak, pin `image:` in `docker-compose.yml` to that version and start over with `docker compose down -v && docker compose up -d`. The suite is exercised in CI against Keycloak 19.0, 21.0, 23.0, 25.0 and 26.7.0.
+
+Everything can also run inside a container:
 
 ```
   $ docker build . -t keycloak-admin:test
@@ -934,6 +995,6 @@ scoped RubyGems credential.
 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
+  $ git tag -a v2.0.3 -m "Version 2.0.3"
+  $ git push origin v2.0.3
 ```

data/keycloak-admin.gemspec

@@ -31,4 +31,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "byebug",  "12.0.0"
   spec.add_development_dependency "rake",    ">= 13.0"
   spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class AttackDetectionClient < Client
     def initialize(configuration, realm_client)
@@ -33,7 +34,7 @@ module KeycloakAdmin
 
     def brute_force_url(user_id = nil)
       if user_id
-        "#{@realm_client.realm_admin_url}/attack-detection/brute-force/users/#{user_id}"
+        "#{@realm_client.realm_admin_url}/attack-detection/brute-force/users/#{encode_segment(user_id)}"
       else
         "#{@realm_client.realm_admin_url}/attack-detection/brute-force/users"
       end

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

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
 require "uri"
 
 module KeycloakAdmin
   class Client
+    include PathEncoding
 
     def initialize(configuration)
       @configuration = configuration
@@ -15,7 +17,7 @@ module KeycloakAdmin
     # 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
-      @configuration.cached_token || @configuration.cache_token(fetch_token)
+      @configuration.fetch_token_once { fetch_token }
     end
 
     def headers
@@ -63,8 +65,10 @@ module KeycloakAdmin
     private
 
     def build_query(parameters)
-      parameters.map do |name, value|
-        "#{URI.encode_uri_component(name.to_s)}=#{URI.encode_uri_component(value.to_s)}"
+      parameters.flat_map do |name, value|
+        encoded_name = URI.encode_uri_component(name.to_s)
+        values       = value.is_a?(Array) ? value : [value]
+        values.map { |single_value| "#{encoded_name}=#{URI.encode_uri_component(single_value.to_s)}" }
       end.join("&")
     end
 
@@ -72,8 +76,17 @@ module KeycloakAdmin
       KeycloakAdmin.create_client(@configuration, @configuration.client_realm_name).token.get
     end
 
+    def connection_options
+      adapter = @configuration.faraday_adapter
+      if adapter.nil?
+        @configuration.faraday_options
+      else
+        @configuration.faraday_options.merge(adapter: adapter)
+      end
+    end
+
     def resource(url)
-      Resource.new(url, @configuration.faraday_options, @configuration.logger)
+      Resource.new(url, connection_options, @configuration.logger)
     end
   end
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientAuthzPermissionClient < Client
     def initialize(configuration, realm_client, client_id, type, resource_id = nil)
@@ -55,11 +56,11 @@ module KeycloakAdmin
 
     def authz_permission_url(client_id, resource_id = nil, type = nil, id = nil)
       if resource_id
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/resource/#{resource_id}/permissions"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/resource/#{encode_segment(resource_id)}/permissions"
       elsif id
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/permission/#{type}/#{id}"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/permission/#{encode_segment(type)}/#{encode_segment(id)}"
       else
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/permission/#{type}"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/permission/#{encode_segment(type)}"
       end
     end
 

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientAuthzPolicyClient < Client
     def initialize(configuration, realm_client, client_id, type)
@@ -55,9 +56,9 @@ module KeycloakAdmin
 
     def authz_policy_url(client_id, type, id = nil)
       if id
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/policy/#{type}/#{id}"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/policy/#{encode_segment(type)}/#{encode_segment(id)}"
       else
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/policy/#{type}?permission=false"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/policy/#{encode_segment(type)}?permission=false"
       end
     end
 

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientAuthzResourceClient < Client
     def initialize(configuration, realm_client, client_id)
@@ -22,17 +23,20 @@ module KeycloakAdmin
     end
 
     def update(resource_id, client_authz_resource_representation)
-      raise "scope[:name] is mandatory and the only necessary attribute to add scope to resource" if client_authz_resource_representation[:scopes] && client_authz_resource_representation[:scopes].any?{|a| !a[:name]}
+      submitted = client_authz_resource_representation || {}
+      if submitted[:scopes]&.any? { |scope| !scope[:name] }
+        raise ArgumentError.new("scope[:name] is mandatory and the only necessary attribute to add scope to resource")
+      end
 
       existing_resource = get(resource_id)
       new_resource = build(
-        client_authz_resource_representation[:name] || existing_resource.name,
-        client_authz_resource_representation[:type] || existing_resource.type,
-        (client_authz_resource_representation[:uris] || [] ) + existing_resource.uris,
-        client_authz_resource_representation[:owner_managed_access] || existing_resource.owner_managed_access,
-        client_authz_resource_representation[:display_name] || existing_resource.display_name,
-        (client_authz_resource_representation[:scopes] || []) + existing_resource.scopes.map{|s| {name: s.name}},
-        client_authz_resource_representation[:attributes] || existing_resource.attributes
+        submitted.fetch(:name, existing_resource.name),
+        submitted.fetch(:type, existing_resource.type),
+        submitted.fetch(:uris, existing_resource.uris),
+        submitted.fetch(:owner_managed_access, existing_resource.owner_managed_access),
+        submitted.fetch(:display_name, existing_resource.display_name),
+        submitted.fetch(:scopes, existing_resource.scopes.map { |scope| {name: scope.name} }),
+        submitted.fetch(:attributes, existing_resource.attributes)
       )
 
       execute_http do
@@ -69,9 +73,9 @@ module KeycloakAdmin
 
     def authz_resources_url(client_id, id = nil)
       if id
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/resource/#{id}"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/resource/#{encode_segment(id)}"
       else
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/resource"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/resource"
       end
     end
 

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientAuthzScopeClient < Client
     def initialize(configuration, realm_client, client_id, resource_id = nil)
@@ -44,11 +45,11 @@ module KeycloakAdmin
 
     def authz_scopes_url(client_id, resource_id = nil, id = nil)
       if resource_id
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/resource/#{resource_id}/scopes"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/resource/#{encode_segment(resource_id)}/scopes"
       elsif id
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/scope/#{id}"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/scope/#{encode_segment(id)}"
       else
-        "#{@realm_client.realm_admin_url}/clients/#{client_id}/authz/resource-server/scope"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(client_id)}/authz/resource-server/scope"
       end
     end
 

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientClient < Client
     def initialize(configuration, realm_client)
@@ -29,7 +30,10 @@ module KeycloakAdmin
     end
 
     def find_by_client_id(client_id)
-      list.find { |client| client.client_id == client_id }
+      response = execute_http do
+        resource("#{clients_url}?#{build_query(clientId: client_id)}").get(headers)
+      end
+      JSON.parse(response).map { |client_as_hash| ClientRepresentation.from_hash(client_as_hash) }.first
     end
 
     def delete(id)
@@ -58,7 +62,7 @@ module KeycloakAdmin
 
     def clients_url(id=nil)
       if id
-        "#{@realm_client.realm_admin_url}/clients/#{id}"
+        "#{@realm_client.realm_admin_url}/clients/#{encode_segment(id)}"
       else
         "#{@realm_client.realm_admin_url}/clients"
       end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientRoleClient < Client
     def initialize(configuration, realm_client)
@@ -14,7 +15,7 @@ module KeycloakAdmin
     end
 
     def clients_url(id)
-      "#{@realm_client.realm_admin_url}/clients/#{id}/roles"
+      "#{@realm_client.realm_admin_url}/clients/#{encode_segment(id)}/roles"
     end
   end
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientRoleMappingsClient < Client
     def initialize(configuration, user_resource, client_id)
@@ -22,11 +23,11 @@ module KeycloakAdmin
     end
 
     def list_available_url
-      "#{@user_resource.resource_url}/role-mappings/clients/#{@client_id}/available"
+      "#{@user_resource.resource_url}/role-mappings/clients/#{encode_segment(@client_id)}/available"
     end
 
     def base_url
-      "#{@user_resource.resource_url}/role-mappings/clients/#{@client_id}"
+      "#{@user_resource.resource_url}/role-mappings/clients/#{encode_segment(@client_id)}"
     end
   end
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientScopeClient < Client
     def initialize(configuration, realm_client)
@@ -59,7 +60,7 @@ module KeycloakAdmin
     def client_scopes_url(client_scope_id = nil)
       base = "#{@realm_client.realm_admin_url}/client-scopes"
 
-      client_scope_id ? "#{base}/#{client_scope_id}" : base
+      client_scope_id ? "#{base}/#{encode_segment(client_scope_id)}" : base
     end
   end
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ClientScopeProtocolMapperClient < Client
     def initialize(configuration, realm_client, client_scope_id)
@@ -54,9 +55,9 @@ module KeycloakAdmin
     end
 
     def protocol_mappers_url(mapper_id = nil)
-      base = "#{@realm_client.realm_admin_url}/client-scopes/#{@client_scope_id}/protocol-mappers/models"
+      base = "#{@realm_client.realm_admin_url}/client-scopes/#{encode_segment(@client_scope_id)}/protocol-mappers/models"
 
-      mapper_id ? "#{base}/#{mapper_id}" : base
+      mapper_id ? "#{base}/#{encode_segment(mapper_id)}" : base
     end
   end
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class ConfigurableTokenClient < Client
     def initialize(configuration, realm_client)
@@ -17,7 +18,7 @@ module KeycloakAdmin
     def exchange_with(user_access_token, token_lifespan_in_seconds)
       response = execute_http do
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             method: :post,
             url: token_url,
             payload: { tokenLifespanInSeconds: token_lifespan_in_seconds }.to_json,

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class GroupClient < Client
     def initialize(configuration, realm_client)
@@ -21,8 +22,16 @@ module KeycloakAdmin
       JSON.parse(response).map { |group_as_hash| GroupRepresentation.from_hash(group_as_hash) }
     end
 
-    def list
-      search(nil)
+    # Unlike the users endpoint, this one applies no default cap: a bare list already returns
+    # every group. Passing neither bound sends no query parameter at all, exactly as before.
+    #
+    # Keycloak 19 only paginates here when both bounds are present - a lone `max` is ignored and
+    # the whole list comes back. Sending `first=0` alongside it makes the call behave the same on
+    # every supported version, and is a no-op from Keycloak 23 on.
+    def list(first: nil, max: nil)
+      first = 0 if first.nil? && !max.nil?
+      pagination = {first: first, max: max}.compact
+      search(pagination.empty? ? nil : pagination)
     end
 
     def search(query)
@@ -111,7 +120,7 @@ module KeycloakAdmin
       url = "#{groups_url(group_id)}/role-mappings/realm"
       execute_http do
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             url: url,
             method: :delete,
             payload: create_payload([role_representation]),
@@ -125,7 +134,7 @@ module KeycloakAdmin
 
     def groups_url(id=nil)
       if id
-        "#{@realm_client.realm_admin_url}/groups/#{id}"
+        "#{@realm_client.realm_admin_url}/groups/#{encode_segment(id)}"
       else
         "#{@realm_client.realm_admin_url}/groups"
       end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class IdentityProviderClient < Client
     def initialize(configuration, realm_client)
@@ -38,7 +39,7 @@ module KeycloakAdmin
 
     def identity_providers_url(internal_id_or_alias=nil)
       if internal_id_or_alias
-        "#{@realm_client.realm_admin_url}/identity-provider/instances/#{internal_id_or_alias}"
+        "#{@realm_client.realm_admin_url}/identity-provider/instances/#{encode_segment(internal_id_or_alias)}"
       else
         "#{@realm_client.realm_admin_url}/identity-provider/instances"
       end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class OrganizationClient < Client
     def initialize(configuration, realm_client)
@@ -69,7 +70,7 @@ module KeycloakAdmin
     def get_identity_provider(organization_id, identity_provider_alias)
       raise ArgumentError.new("identity_provider_alias must be defined") if identity_provider_alias.nil?
       response = execute_http do
-        resource("#{identity_providers_url(organization_id)}/#{identity_provider_alias}").get(headers)
+        resource(identity_provider_url(organization_id, identity_provider_alias)).get(headers)
       end
       IdentityProviderRepresentation.from_hash(JSON.parse(response))
     end
@@ -157,7 +158,7 @@ module KeycloakAdmin
 
     def organization_url(organization_id)
       raise ArgumentError.new("organization_id must be defined") if organization_id.nil?
-      "#{organizations_url}/#{organization_id}"
+      "#{organizations_url}/#{encode_segment(organization_id)}"
     end
 
     def identity_providers_url(organization_id)
@@ -166,7 +167,7 @@ module KeycloakAdmin
 
     def identity_provider_url(organization_id, identity_provider_alias)
       raise ArgumentError.new("identity_provider_alias must be defined") if identity_provider_alias.nil?
-      "#{identity_providers_url(organization_id)}/#{identity_provider_alias}"
+      "#{identity_providers_url(organization_id)}/#{encode_segment(identity_provider_alias)}"
     end
 
     def count_url(exact, query, search)
@@ -187,7 +188,7 @@ module KeycloakAdmin
     end
 
     def associated_with_member_url(member_id, brief_representation=true)
-      "#{organizations_url}/members/#{member_id}/organizations?#{build_query(briefRepresentation: brief_representation)}"
+      "#{organizations_url}/members/#{encode_segment(member_id)}/organizations?#{build_query(briefRepresentation: brief_representation)}"
     end
 
     def members_count_url(organization_id)
@@ -196,7 +197,7 @@ module KeycloakAdmin
 
     def member_url(organization_id, member_id)
       raise ArgumentError.new("member_id must be defined") if member_id.nil?
-      "#{organization_url(organization_id)}/members/#{member_id}"
+      "#{organization_url(organization_id)}/members/#{encode_segment(member_id)}"
     end
 
     def invite_existing_user_url(organization_id)

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class RealmClient < Client
     def initialize(configuration, realm_name=nil)
@@ -37,7 +38,7 @@ module KeycloakAdmin
 
     def realm_url
       if @realm_name
-        "#{server_url}/realms/#{@realm_name}"
+        "#{server_url}/realms/#{encode_segment(@realm_name)}"
       else
         "#{server_url}/realms"
       end
@@ -45,7 +46,7 @@ module KeycloakAdmin
 
     def realm_admin_url
       if @realm_name
-        "#{server_url}/admin/realms/#{@realm_name}"
+        "#{server_url}/admin/realms/#{encode_segment(@realm_name)}"
       else
         "#{server_url}/admin/realms"
       end