keycloak-admin 2.0.1 → 2.0.3

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)
@@ -75,11 +84,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
@@ -114,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]),
@@ -128,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,28 +167,28 @@ 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)
-      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/#{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)
@@ -212,19 +213,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/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

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "faraday"
 require "uri"
 
@@ -18,13 +19,11 @@ module KeycloakAdmin
       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)
+      options  = (options || {}).dup
+      @adapter = options.delete(:adapter)
       @url     = url
-      @options = options || {}
+      @options = options
       @logger  = logger
     end
 
@@ -75,7 +74,10 @@ module KeycloakAdmin
         # 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
+        # Faraday's default net_http adapter wraps every request in http.start, which reopens
+        # the connection each time; config.faraday_adapter lets a caller swap in a pooling one.
+        # Splatted so an adapter needing arguments can be given as [:name, options].
+        f.adapter(*Array(@adapter || Faraday.default_adapter))
       end
     end
 

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 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)

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class RoleClient < Client
     def initialize(configuration, realm_client)
@@ -15,8 +16,6 @@ module KeycloakAdmin
 
     # Returns the role representation for the specified role name
     def get(name)
-      # allows special characters in the name like space
-      name = URI.encode_uri_component(name)
       response = execute_http do
         resource(role_name_url(name)).get(headers)
       end
@@ -25,8 +24,6 @@ module KeycloakAdmin
 
     # Lists all groups that have the specified role name assigned
     def list_groups(name)
-      # allows special characters in the name like space
-      name = URI.encode_uri_component(name)
       response = execute_http do
         resource("#{role_name_url(name)}/groups").get(headers)
       end
@@ -49,11 +46,11 @@ module KeycloakAdmin
     end
 
     def role_id_url(id)
-      "#{@realm_client.realm_admin_url}/roles-by-id/#{id}"
+      "#{@realm_client.realm_admin_url}/roles-by-id/#{encode_segment(id)}"
     end
     
     def role_name_url(name)
-      "#{@realm_client.realm_admin_url}/roles/#{name}"
+      "#{@realm_client.realm_admin_url}/roles/#{encode_segment(name)}"
     end
   end
 end

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class RoleMapperClient < Client
     def initialize(configuration, user_resource)
@@ -23,7 +24,7 @@ module KeycloakAdmin
     def remove_realm_level(role_representation_list)
       execute_http do
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             method: :delete,
             url: realm_level_url,
             payload: create_payload(role_representation_list),

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class TokenClient < Client
     def initialize(configuration, realm_client)

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

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class UserClient < Client
     def initialize(configuration, realm_client)
@@ -6,55 +7,61 @@ module KeycloakAdmin
       @realm_client = realm_client
     end
 
+    # Reads the id of the new user off the Location header rather than searching for it
+    # afterwards: Keycloak's `search` parameter matches a substring of the username, email,
+    # first name or last name, so an existing user merely containing this email was returned
+    # instead of the one just created.
     def create!(username, email, password, email_verified, locale, attributes={})
-      user = save(build(username, email, password, email_verified, locale, attributes))
-      search(user.email)&.first
+      response = post_user(build(username, email, password, email_verified, locale, attributes))
+      get(created_id(response))
     end
 
     def save(user_representation)
-      execute_http do
-        resource(users_url).post(
-          create_payload(user_representation), headers
-        )
-      end
+      post_user(user_representation)
       user_representation
     end
 
     # pay attention that, since Keycloak 24.0.4, partial updates of attributes are not authorized anymore
     def update(user_id, user_representation_body)
       raise ArgumentError.new("user_id must be defined") if user_id.nil?
-      Resource.execute(
-        @configuration.faraday_options.merge(
-          method: :put,
-          url: users_url(user_id),
-          payload: create_payload(user_representation_body),
-          headers: headers,
-          logger: @configuration.logger
+      execute_http do
+        Resource.execute(
+          connection_options.merge(
+            method: :put,
+            url: users_url(user_id),
+            payload: create_payload(user_representation_body),
+            headers: headers,
+            logger: @configuration.logger
+          )
         )
-      )
+      end
     end
 
     def add_group(user_id, group_id)
-      Resource.execute(
-        @configuration.faraday_options.merge(
-          method: :put,
-          url: "#{users_url(user_id)}/groups/#{group_id}",
-          payload: create_payload({}),
-          headers: headers,
-          logger: @configuration.logger
+      execute_http do
+        Resource.execute(
+          connection_options.merge(
+            method: :put,
+            url: "#{users_url(user_id)}/groups/#{encode_segment(group_id)}",
+            payload: create_payload({}),
+            headers: headers,
+            logger: @configuration.logger
+          )
         )
-      )
+      end
     end
 
     def remove_group(user_id, group_id)
-      Resource.execute(
-        @configuration.faraday_options.merge(
-          method: :delete,
-          url: "#{users_url(user_id)}/groups/#{group_id}",
-          headers: headers,
-          logger: @configuration.logger
+      execute_http do
+        Resource.execute(
+          connection_options.merge(
+            method: :delete,
+            url: "#{users_url(user_id)}/groups/#{encode_segment(group_id)}",
+            headers: headers,
+            logger: @configuration.logger
+          )
         )
-      )
+      end
     end
 
     def add_client_roles_on_user(user_id, client_id, role_representations)
@@ -94,8 +101,12 @@ module KeycloakAdmin
       JSON.parse(response).map { |user_as_hash| UserRepresentation.from_hash(user_as_hash) }
     end
 
-    def list
-      search(nil)
+    # Keycloak answers this endpoint with at most 100 users unless `max` says otherwise, so a
+    # bare `list` silently truncates a larger realm. Passing neither bound sends no query
+    # parameter at all, exactly as before.
+    def list(first: nil, max: nil)
+      pagination = {first: first, max: max}.compact
+      search(pagination.empty? ? nil : pagination)
     end
 
     def delete(user_id)
@@ -112,13 +123,13 @@ module KeycloakAdmin
       JSON.parse(response).map { |group_as_hash| GroupRepresentation.from_hash(group_as_hash) }
     end
 
-    def update_password(user_id, new_password)
+    def update_password(user_id, new_password, temporary: false)
       execute_http do
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             method: :put,
             url: reset_password_url(user_id),
-            payload: { type: "password", value: new_password, temporary: false }.to_json,
+            payload: { type: "password", value: new_password, temporary: temporary }.to_json,
             headers: headers,
             logger: @configuration.logger
           )
@@ -141,19 +152,23 @@ 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, @configuration.logger)
+        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(url).put(create_payload(actions), headers)
       end
       user_id
     end
 
     def impersonate(user_id)
-      impersonation = get_redirect_impersonation(user_id)
       response = execute_http do
+        impersonation = get_redirect_impersonation(user_id)
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             method: :post,
             url: impersonation.impersonation_url,
             payload: impersonation.body.to_json,
@@ -179,7 +194,7 @@ module KeycloakAdmin
 
       execute_http do
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             method: :post,
             url: logout_url(user_id),
             headers: headers,
@@ -202,7 +217,7 @@ module KeycloakAdmin
 
       execute_http do
         Resource.execute(
-          @configuration.faraday_options.merge(
+          connection_options.merge(
             method: :post,
             url: federated_identity_url(user_id, idp_id),
             payload: fed_id_rep.to_json,
@@ -221,14 +236,14 @@ module KeycloakAdmin
 
     def users_url(id=nil)
       if id
-        "#{@realm_client.realm_admin_url}/users/#{id}"
+        "#{@realm_client.realm_admin_url}/users/#{encode_segment(id)}"
       else
         "#{@realm_client.realm_admin_url}/users"
       end
     end
 
     def user_client_role_mappings_url(user_id, client_id)
-      "#{users_url(user_id)}/role-mappings/clients/#{client_id}"
+      "#{users_url(user_id)}/role-mappings/clients/#{encode_segment(client_id)}"
     end
 
     def reset_password_url(user_id)
@@ -259,7 +274,7 @@ module KeycloakAdmin
     def federated_identity_url(user_id, identity_provider)
       raise ArgumentError.new("user_id must be defined") if user_id.nil?
       raise ArgumentError.new("identity_provider must be defined") if identity_provider.nil?
-      "#{users_url(user_id)}/federated-identity/#{identity_provider}"
+      "#{users_url(user_id)}/federated-identity/#{encode_segment(identity_provider)}"
     end
 
     def logout_url(user_id)
@@ -270,13 +285,21 @@ module KeycloakAdmin
 
     private
 
+    def post_user(user_representation)
+      execute_http do
+        resource(users_url).post(
+          create_payload(user_representation), headers
+        )
+      end
+    end
+
     def build(username, email, password, email_verified, locale, attributes={})
       user                     = UserRepresentation.new
       user.email               = email
       user.username            = username
       user.email_verified      = email_verified
       user.enabled             = true
-      user.attributes          = attributes || {}
+      user.attributes          = (attributes || {}).dup
       user.attributes[:locale] = locale if locale
       user.add_credential(CredentialRepresentation.from_password(password)) if !password.nil?
       user

data/lib/keycloak-admin/configuration.rb

@@ -1,13 +1,48 @@
+# frozen_string_literal: true
 require "base64"
 
 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
+    attr_accessor :server_url, :server_domain, :client_id, :client_secret, :client_realm_name, :use_service_account, :username, :password, :logger, :faraday_options, :faraday_adapter
 
     # 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
 
+    FILTERED_ATTRIBUTES  = %i[@client_secret @password @cached_token].freeze
+    FILTERED_PLACEHOLDER = "[FILTERED]".freeze
+
+    def initialize
+      @token_mutex = Mutex.new
+    end
+
+    def inspect
+      rendered = instance_variables.map do |name|
+        value = instance_variable_get(name)
+        shown  = if FILTERED_ATTRIBUTES.include?(name) && !value.nil?
+          FILTERED_PLACEHOLDER
+        else
+          value.inspect
+        end
+        "#{name}=#{shown}"
+      end
+      "#<#{self.class.name} #{rendered.join(", ")}>"
+    end
+
+    # Returns the cached token, fetching one through the block if there is none.
+    # The block runs at most once across threads.
+    def fetch_token_once
+      token = cached_token
+      if token.nil?
+        @token_mutex.synchronize do
+          token = cached_token
+          token.nil? ? cache_token(yield) : token
+        end
+      else
+        token
+      end
+    end
+
     # 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
@@ -22,8 +57,8 @@ module KeycloakAdmin
     end
 
     def clear_cached_token!
-      @cached_token     = nil
       @token_expires_at = nil
+      @cached_token     = nil
     end
 
     def body_for_token_retrieval

data/lib/keycloak-admin/error.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+module KeycloakAdmin
+  class Error < StandardError; end
+
+  # Raised when Keycloak answers with a non-2xx status.
+  #
+  # Callers can rescue the precise failure (KeycloakAdmin::NotFoundError), a whole family
+  # (KeycloakAdmin::ClientError for any 4xx) or every HTTP failure (KeycloakAdmin::ApiError),
+  # and read #status/#body off the exception rather than parsing the message.
+  class ApiError < Error
+    attr_reader :status, :body, :headers
+
+    def initialize(status, body, headers = {})
+      @status  = status
+      @body    = body
+      @headers = headers || {}
+      super("Keycloak: The request failed with response code #{status} and message: #{body}")
+    end
+
+    def self.from_response(response)
+      response ||= {}
+      status     = response[:status]
+      error_class_for(status).new(status, response[:body], response[:headers])
+    end
+
+    def self.error_class_for(status)
+      case status
+      when 400      then BadRequestError
+      when 401      then UnauthorizedError
+      when 403      then ForbiddenError
+      when 404      then NotFoundError
+      when 409      then ConflictError
+      when 400..499 then ClientError
+      when 500..599 then ServerError
+      else ApiError
+      end
+    end
+  end
+
+  # Any 4xx: the request itself was rejected.
+  class ClientError < ApiError; end
+
+  class BadRequestError   < ClientError; end
+  class UnauthorizedError < ClientError; end
+  class ForbiddenError    < ClientError; end
+  class NotFoundError     < ClientError; end
+  class ConflictError     < ClientError; end
+
+  # Any 5xx: Keycloak accepted the request but failed to serve it.
+  class ServerError < ApiError; end
+
+  # Raised when a create call succeeds at the HTTP level but answers something other than
+  # 201 Created, leaving no Location header to read the new resource's id from.
+  class UnexpectedResponseError < Error
+    attr_reader :status, :reason_phrase
+
+    def initialize(status, reason_phrase)
+      @status        = status
+      @reason_phrase = reason_phrase
+      super("Create method returned status #{reason_phrase} (Code: #{status}); expected status: Created (201)")
+    end
+  end
+end

data/lib/keycloak-admin/path_encoding.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require "uri"
+
+module KeycloakAdmin
+  # Percent-encoding for the identifiers interpolated into a URL path.
+  #
+  # Included by Client and BaseRoleContainingResource, which have no common ancestor but
+  # both build URLs out of caller-supplied values.
+  module PathEncoding
+    private
+
+    # Encodes '/' as %2F too, so an identifier can never open a path segment of its own.
+    # Values that are already URL-safe - the UUIDs Keycloak hands out - come out unchanged,
+    # so this is a no-op for the usual case.
+    #
+    # Without it, any identifier holding a character that is illegal in a URI (a space, most
+    # obviously) made Ruby's URI parser raise URI::InvalidURIError before the request was
+    # ever sent. That is reachable with values users choose themselves, identity provider
+    # aliases being the clearest case.
+    def encode_segment(value)
+      URI.encode_uri_component(value.to_s)
+    end
+  end
+end

data/lib/keycloak-admin/representation/attack_detection_representation.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module KeycloakAdmin
   class AttackDetectionRepresentation < Representation
     attr_accessor :num_failures,