keycloak-api-rails 1.1.2 → 2.0.2

data/lib/keycloak-api-rails/middleware.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
 
   class Middleware
@@ -8,36 +10,43 @@ module KeycloakApiRails
     def call(env)
       method = env["REQUEST_METHOD"]
       path   = env["PATH_INFO"]
-      uri    = env["REQUEST_URI"]
 
       if service.need_middleware_authentication?(method, path, env)
         logger.debug("Start authentication for #{method} : #{path}")
-        token         = service.read_token(uri, env)
-        decoded_token = service.decode_and_verify(token)
-        authentication_succeeded(env, decoded_token)
+        begin
+          authenticate(env)
+        rescue TokenError => e
+          logger.debug("The error causing the Token to fail: #{e.original_error&.message || e.message}")
+          return authentication_failed(e.message)
+        rescue HTTPError, MissingPublicKeysError => e
+          logger.error("KeycloakApiRails: no token can be verified for #{method} : #{path}. #{e.class}: #{e.message}")
+          return authentication_unavailable
+        end
       else
         logger.debug("Skip authentication for #{method} : #{path}")
-        @app.call(env)
       end
-    rescue TokenError => e
-      logger.debug("The error causing the Token to fail: #{e.original_error&.message || e.message}")
-      authentication_failed(e.message)
+
+      @app.call(env)
+    end
+
+    private
+
+    def authenticate(env)
+      token         = service.read_token(Helper.request_uri(env), env)
+      decoded_token = service.decode_and_verify(token)
+      Helper.assign_token(env, decoded_token, config.custom_attributes)
     end
 
     def authentication_failed(message)
-      [401, {"Content-Type" => "application/json"}, [ { error: message }.to_json]]
-    end
-
-    def authentication_succeeded(env, decoded_token)
-      Helper.assign_current_user_id(env, decoded_token)
-      Helper.assign_current_authorized_party(env, decoded_token)
-      Helper.assign_current_user_email(env, decoded_token)
-      Helper.assign_current_user_locale(env, decoded_token)
-      Helper.assign_current_user_custom_attributes(env, decoded_token, config.custom_attributes)
-      Helper.assign_realm_roles(env, decoded_token)
-      Helper.assign_resource_roles(env, decoded_token)
-      Helper.assign_keycloak_token(env, decoded_token)
-      @app.call(env)
+      # Rack 3 requires header names to be lowercase.
+      [401, { "content-type" => "application/json" }, [{ error: message }.to_json]]
+    end
+
+    def authentication_unavailable
+      [503,
+       { "content-type" => "application/json",
+         "retry-after"  => PublicKeyCachedResolver::FAILED_REFRESH_RETRY_DELAY_IN_SECONDS.to_s },
+       [{ error: "Authentication is temporarily unavailable" }.to_json]]
     end
 
     def service

data/lib/keycloak-api-rails/public_key_cached_resolver.rb

@@ -1,30 +1,90 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class PublicKeyCachedResolver
-    attr_reader :cached_public_key_retrieved_at
+    FAILED_REFRESH_RETRY_DELAY_IN_SECONDS = 10
 
-    def initialize(http_client, realm_id, public_key_cache_ttl)
-      @resolver                       = PublicKeyResolver.new(http_client, realm_id)
-      @public_key_cache_ttl           = public_key_cache_ttl
-      @cached_public_keys             = nil
-      @cached_public_key_retrieved_at = nil
-    end
+    class RealmCache
+      attr_reader :cached_public_key_retrieved_at
 
-    def self.from_configuration(http_client, configuration)
-      PublicKeyCachedResolver.new(http_client, configuration.realm_id, configuration.public_key_cache_ttl)
-    end
+      def initialize(http_client, realm_id)
+        @resolver                       = PublicKeyResolver.new(http_client, realm_id)
+        @cached_public_keys             = nil
+        @cached_public_key_retrieved_at = nil
+        @last_refresh_failure_at        = nil
+        @last_refresh_error             = nil
+        @mutex                          = Mutex.new
+      end
+
+      def find_public_keys(public_key_cache_ttl, logger)
+        @mutex.synchronize do
+          raise @last_refresh_error if refresh_recently_failed_without_any_cache?
 
-    def find_public_keys
-      if public_keys_are_outdated?
+          refresh_public_keys(logger) if public_keys_are_outdated?(public_key_cache_ttl)
+          @cached_public_keys
+        end
+      end
+
+      private
+
+      def refresh_public_keys(logger)
         @cached_public_keys             = @resolver.find_public_keys
         @cached_public_key_retrieved_at = Time.now
+        @last_refresh_failure_at        = nil
+        @last_refresh_error             = nil
+      rescue StandardError => e
+        @last_refresh_failure_at = Time.now
+        @last_refresh_error      = e
+        raise if @cached_public_keys.nil?
+
+        logger&.warn("KeycloakApiRails: could not refresh the public keys (#{e.class}: #{e.message}). Keeping the ones retrieved at #{@cached_public_key_retrieved_at}.")
+      end
+
+      def refresh_recently_failed_without_any_cache?
+        @cached_public_keys.nil? &&
+          !@last_refresh_failure_at.nil? &&
+          Time.now <= @last_refresh_failure_at + FAILED_REFRESH_RETRY_DELAY_IN_SECONDS
       end
-      @cached_public_keys
+
+      def public_keys_are_outdated?(public_key_cache_ttl)
+        @cached_public_keys.nil? ||
+          @cached_public_key_retrieved_at.nil? ||
+          (Time.now > @cached_public_key_retrieved_at + public_key_cache_ttl &&
+            (@last_refresh_failure_at.nil? ||
+              Time.now > @last_refresh_failure_at + FAILED_REFRESH_RETRY_DELAY_IN_SECONDS))
+      end
+    end
+
+    def initialize(http_client, realm_id, public_key_cache_ttl, logger = nil)
+      @http_client          = http_client
+      @realm_id             = realm_id
+      @public_key_cache_ttl = public_key_cache_ttl
+      @logger               = logger
+      @caches               = {}
+      @caches_mutex         = Mutex.new
+    end
+
+    def self.from_configuration(http_client, configuration)
+      new(http_client, configuration.realm_id, configuration.public_key_cache_ttl, configuration.logger)
+    end
+
+    def find_public_keys(realm_id = nil)
+      target_realm = realm_id || @realm_id
+      cache_for(target_realm).find_public_keys(@public_key_cache_ttl, @logger)
+    end
+
+    # Keep this method backward-compatible for testing
+    def cached_public_key_retrieved_at(realm_id = nil)
+      target_realm = realm_id || @realm_id
+      cache_for(target_realm).cached_public_key_retrieved_at
     end
 
     private
 
-    def public_keys_are_outdated?
-      @cached_public_keys.nil? || @cached_public_key_retrieved_at.nil? || Time.now > (@cached_public_key_retrieved_at + @public_key_cache_ttl)
+    def cache_for(realm_id)
+      @caches_mutex.synchronize do
+        @caches[realm_id] ||= RealmCache.new(@http_client, realm_id)
+      end
     end
   end
 end

data/lib/keycloak-api-rails/public_key_resolver.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class PublicKeyResolver
     def initialize(http_client, realm_id)

data/lib/keycloak-api-rails/railtie.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class Railtie < Rails::Railtie
     railtie_name :keycloak_api_rails
@@ -5,5 +7,20 @@ module KeycloakApiRails
     initializer("keycloak.insert_middleware") do |app|
       app.config.middleware.use(KeycloakApiRails::Middleware)
     end
+
+    # Runs once every initializer has run, config/initializers/keycloak.rb included, so that a
+    # misconfiguration fails at boot instead of on the first request reaching the middleware.
+    config.after_initialize do
+      keycloak_configuration = KeycloakApiRails.config
+      keycloak_configuration.validate!
+
+      unless keycloak_configuration.server_configured?
+        keycloak_configuration.logger.warn(
+          "KeycloakApiRails: 'server_url' and 'realm_id' are not both configured. No token can be " \
+          "verified until they are, unless the public key resolver is replaced -- as " \
+          "\"keycloak-api-rails/testing\" does."
+        )
+      end
+    end
   end
-end
+end

data/lib/keycloak-api-rails/service.rb

@@ -1,38 +1,80 @@
+# frozen_string_literal: true
+
+require 'base64'
 module KeycloakApiRails
+  class MissingPublicKeysError < StandardError; end
+
   class Service
-    
+
     def initialize(key_resolver)
+      configuration                          = KeycloakApiRails.config
       @key_resolver                          = key_resolver
-      @skip_paths                            = KeycloakApiRails.config.skip_paths
-      @opt_in                                = KeycloakApiRails.config.opt_in
-      @logger                                = KeycloakApiRails.config.logger
-      @token_expiration_tolerance_in_seconds = KeycloakApiRails.config.token_expiration_tolerance_in_seconds
+      @skip_paths                            = normalize_skip_paths(configuration.skip_paths, configuration.logger)
+      @opt_in                                = configuration.opt_in
+      @token_expiration_tolerance_in_seconds = configuration.token_expiration_tolerance_in_seconds
+      @expected_audiences                    = Array(configuration.expected_audience).map(&:to_s)
+      @expected_token_type                   = configuration.expected_token_type
+      @verify_not_before                     = configuration.verify_not_before
+      @allow_token_in_query_string           = configuration.allow_token_in_query_string
     end
 
     def decode_and_verify(token)
-      unless token.nil? || token&.empty?
-        public_key    = @key_resolver.find_public_keys
-        decoded_token = JSON::JWT.decode(token, public_key)
-
-        unless expired?(decoded_token)
-          decoded_token.verify!(public_key)
-          decoded_token
-        else
-          raise TokenError.expired(token)
-        end
+      raise TokenError.no_token(token) if token.nil? || token.empty?
+      
+      parts = token.to_s.split('.')
+      raise TokenError.invalid_format(token) if parts.length < 3
+
+      realm_id = extract_realm_from_token(token)
+      raise TokenError.invalid_realm(token) unless realm_allowed?(realm_id)
+      
+      public_keys = @key_resolver.find_public_keys(realm_id)
+      
+      if public_keys.nil?
+        raise MissingPublicKeysError, "No Keycloak public key is available to verify the token" 
+      end
+
+      decoded_token = decode(token, public_keys)
+      verify_claims!(token, decoded_token, realm_id)
+      decoded_token
+    end
+
+    def extract_realm_from_token(token)
+      payload_segment = token.split('.', 3)[1]
+      return nil unless payload_segment
+
+      decoded_payload = Base64.urlsafe_decode64(payload_segment)
+      parsed_payload = JSON.parse(decoded_payload)
+      iss = parsed_payload['iss']
+      return nil unless iss
+
+      iss.split('/').last
+    rescue JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def realm_allowed?(realm_id)
+      config_realm_id = KeycloakApiRails.config.realm_id
+      return true if config_realm_id.nil?
+      return false if realm_id.nil?
+
+      if config_realm_id.respond_to?(:call)
+        config_realm_id.call(realm_id)
+      elsif config_realm_id.is_a?(Array)
+        config_realm_id.include?(realm_id)
       else
-        raise TokenError.no_token(token)
+        config_realm_id == realm_id
       end
-    rescue JSON::JWT::VerificationFailed => e
-      raise TokenError.verification_failed(token, e)
-    rescue JSON::JWK::Set::KidNotFound => e
-      raise TokenError.verification_failed(token, e)
-    rescue JSON::JWT::InvalidFormat
-      raise TokenError.invalid_format(token, e)
     end
 
     def read_token(uri, headers)
-      Helper.read_token_from_query_string(uri) || Helper.read_token_from_headers(headers)
+      header_token = Helper.read_token_from_headers(headers)
+      if !header_token.empty?
+        header_token
+      elsif @allow_token_in_query_string
+        Helper.read_token_from_query_string(uri).to_s
+      else
+        ""
+      end
     end
 
     def need_middleware_authentication?(method, path, headers)
@@ -41,20 +83,86 @@ module KeycloakApiRails
 
     private
 
+    def decode(token, public_keys)
+      decoded_token = JSON::JWT.decode(token, public_keys)
+      decoded_token.verify!(public_keys)
+      decoded_token
+    rescue JSON::JWT::VerificationFailed, JSON::JWK::Set::KidNotFound => e
+      raise TokenError.verification_failed(token, e)
+    rescue JSON::JWT::InvalidFormat => e
+      raise TokenError.invalid_format(token, e)
+    rescue StandardError => e
+      raise TokenError.unknown(token, e)
+    end
+
+    # RFC 7519 requires 'exp' and 'nbf' to be NumericDates.
+    def verify_claims!(token, decoded_token, realm_id)
+      raise TokenError.missing_claim(token, "exp") unless decoded_token.key?("exp")
+      raise TokenError.invalid_claim(token, "exp") unless decoded_token["exp"].is_a?(Numeric)
+      raise TokenError.invalid_claim(token, "nbf") if not_before_is_invalid?(decoded_token)
+      raise TokenError.expired(token)              if expired?(decoded_token)
+      raise TokenError.not_yet_valid(token)        if not_yet_valid?(decoded_token)
+      raise TokenError.invalid_audience(token)     unless audience_valid?(decoded_token)
+      raise TokenError.invalid_token_type(token)   unless token_type_valid?(decoded_token)
+
+      if KeycloakApiRails.config.server_url
+        expected_iss = File.join(KeycloakApiRails.config.server_url.to_s, "realms", realm_id.to_s)
+        raise TokenError.invalid_realm(token) unless decoded_token["iss"] == expected_iss
+      end
+    end
+
+    def not_before_is_invalid?(token)
+      @verify_not_before && token.key?("nbf") && !token["nbf"].is_a?(Numeric)
+    end
+
+    # Anything that is not a regexp is discarded rather than matched: 'String#match' compiles its
+    # argument into a regexp, so a String would be matched against the path of the request instead of
+    # the other way around, and would open every path that is a sub-pattern of it. The railtie rejects
+    # such a configuration when the application boots; a Rack application running without Rails never
+    # calls 'validate!', so the paths keep being authenticated here.
+    def normalize_skip_paths(skip_paths, logger)
+      (skip_paths || {}).each_with_object({}) do |(method, paths), normalized|
+        regexps, discarded = Array(paths).partition { |path| path.is_a?(Regexp) }
+
+        unless discarded.empty?
+          logger&.warn("KeycloakApiRails: 'skip_paths[#{method.inspect}]' declares #{discarded.map(&:inspect).join(', ')}, which are not regexps. They are ignored, and the paths they were meant to open keep being authenticated.")
+        end
+
+        normalized[method.to_s.upcase] = regexps
+      end
+    end
+
     def should_skip?(method, path)
-      method_symbol = method&.downcase&.to_sym
-      skip_paths    = @skip_paths[method_symbol]
-      !skip_paths.nil? && !skip_paths.empty? && !skip_paths.find_index { |skip_path| skip_path.match(path) }.nil?
+      skip_paths = @skip_paths[method]
+      !skip_paths.nil? && skip_paths.any? { |skip_path| skip_path.match?(path) }
     end
 
     def is_preflight?(method, headers)
-      method_symbol = method&.downcase&.to_sym
-      method_symbol == :options && !headers["HTTP_ACCESS_CONTROL_REQUEST_METHOD"].nil?
+      method == "OPTIONS" && !headers["HTTP_ACCESS_CONTROL_REQUEST_METHOD"].nil?
     end
 
     def expired?(token)
       token_expiration = Time.at(token["exp"])
       token_expiration < Time.now + @token_expiration_tolerance_in_seconds
     end
+
+    def not_yet_valid?(token)
+      return false unless @verify_not_before
+
+      not_before = token["nbf"]
+      !not_before.nil? && Time.at(not_before) > Time.now
+    end
+
+    def audience_valid?(token)
+      return true if @expected_audiences.empty?
+
+      Array(token["aud"]).any? { |audience| @expected_audiences.include?(audience.to_s) }
+    end
+
+    def token_type_valid?(token)
+      return true if @expected_token_type.nil?
+
+      token["typ"].to_s.casecmp?(@expected_token_type)
+    end
   end
 end

data/lib/keycloak-api-rails/testing.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Test helpers for the applications that authenticate their requests with this library.
 #
 # This file is *not* loaded by "keycloak-api-rails": it has to be required explicitly, so that
@@ -33,24 +35,26 @@ module KeycloakApiRails
         @public_keys = public_keys
       end
 
-      def find_public_keys
+      def find_public_keys(realm_id = nil)
         @public_keys
       end
     end
 
+    MONITOR = Monitor.new
+
     class << self
       # The RSA key pair used to sign the tokens forged by this module. It is generated once per
       # process: generating a key is by far the slowest operation of a test suite that uses tokens.
       def private_key
-        @private_key ||= OpenSSL::PKey::RSA.generate(KEY_SIZE)
+        MONITOR.synchronize { @private_key ||= OpenSSL::PKey::RSA.generate(KEY_SIZE) }
       end
 
       def signing_key
-        @signing_key ||= JSON::JWK.new(private_key, kid: KEY_ID)
+        MONITOR.synchronize { @signing_key ||= JSON::JWK.new(private_key, kid: KEY_ID) }
       end
 
       def public_keys
-        @public_keys ||= JSON::JWK::Set.new(JSON::JWK.new(private_key.public_key, kid: KEY_ID))
+        MONITOR.synchronize { @public_keys ||= JSON::JWK::Set.new(JSON::JWK.new(private_key.public_key, kid: KEY_ID)) }
       end
 
       # Makes the library validate the tokens forged by this module. Assigning
@@ -83,6 +87,12 @@ module KeycloakApiRails
         payload["realm_access"]    = { "roles" => roles.map(&:to_s) } unless roles.nil? || roles.empty?
         payload["resource_access"] = build_resource_access(resource_roles) unless resource_roles.nil? || resource_roles.empty?
 
+        unless claims.key?(:iss) || claims.key?("iss")
+          config_realm_id = KeycloakApiRails.config.realm_id
+          realm_id = config_realm_id.is_a?(String) ? config_realm_id : "master"
+          payload["iss"] = File.join(KeycloakApiRails.config.server_url.to_s, "realms", realm_id)
+        end
+
         claims.each { |name, value| payload[name.to_s] = value }
 
         JSON::JWT.new(payload).sign(signing_key, ALGORITHM).to_s

data/lib/keycloak-api-rails/token_error.rb

@@ -1,30 +1,58 @@
-class TokenError < StandardError
-  attr_reader :token, :reason, :original_error
-
-  def initialize(token, reason, message, original_error)
-    super(message)
-    @token          = token
-    @reason         = reason
-    @original_error = original_error
-  end
+# frozen_string_literal: true
 
-  def self.verification_failed(token, original_error)
-    TokenError.new(token, :verification_failed, "Failed to verify JWT token", original_error)
-  end
+module KeycloakApiRails
+  class TokenError < StandardError
+    attr_reader :token, :reason, :original_error
 
-  def self.invalid_format(token, original_error)
-    TokenError.new(token, :invalid_format, "Wrong JWT Format", original_error)
-  end
+    def initialize(token, reason, message, original_error = nil)
+      super(message)
+      @token          = token
+      @reason         = reason
+      @original_error = original_error
+    end
 
-  def self.no_token(token)
-    TokenError.new(token, :no_token, "No JWT token provided", nil)
-  end
+    def self.verification_failed(token, original_error)
+      new(token, :verification_failed, "Failed to verify JWT token", original_error)
+    end
 
-  def self.expired(token)
-    TokenError.new(token, :expired, "JWT token is expired", nil)
-  end
+    def self.invalid_format(token, original_error = nil)
+      new(token, :invalid_format, "Wrong JWT Format", original_error)
+    end
+
+    def self.invalid_realm(token)
+      new(token, :invalid_realm, "JWT token does not have a valid realm")
+    end
+
+    def self.no_token(token)
+      new(token, :no_token, "No JWT token provided")
+    end
+
+    def self.expired(token)
+      new(token, :expired, "JWT token is expired")
+    end
+
+    def self.not_yet_valid(token)
+      new(token, :not_yet_valid, "JWT token is not valid yet")
+    end
+
+    def self.invalid_audience(token)
+      new(token, :invalid_audience, "JWT token has been issued for another audience")
+    end
+
+    def self.invalid_token_type(token)
+      new(token, :invalid_token_type, "JWT token is not of the expected type")
+    end
+
+    def self.missing_claim(token, claim)
+      new(token, :missing_claim, "JWT token does not carry the mandatory claim '#{claim}'")
+    end
+
+    def self.invalid_claim(token, claim)
+      new(token, :invalid_claim, "JWT token carries an invalid '#{claim}' claim: it must be a number of seconds since the Epoch")
+    end
 
-  def self.unknown(token)
-    TokenError.new
+    def self.unknown(token, original_error)
+      new(token, :unknown, "Failed to read JWT token", original_error)
+    end
   end
 end

data/lib/keycloak-api-rails/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
-  VERSION = "1.1.2"
+  VERSION = "2.0.2"
 end

data/lib/keycloak-api-rails.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 require "logger"
 require "json/jwt"
 require "uri"
 require "date"
+require "monitor"
 require "net/http"
 
 require_relative "keycloak-api-rails/authentication"
@@ -17,32 +20,50 @@ require_relative "keycloak-api-rails/railtie" if defined?(Rails)
 
 module KeycloakApiRails
 
+  # These objects are memoized lazily, on the first request each process serves -- which several
+  # threads of a threaded server reach at the same time. A Monitor rather than a Mutex: the
+  # memoizations nest, 'service' needing 'public_key_resolver', which needs 'http_client'.
+  MONITOR = Monitor.new
+
   def self.configure
-    yield @configuration ||= KeycloakApiRails::Configuration.new
+    MONITOR.synchronize do
+      yield @configuration ||= KeycloakApiRails::Configuration.new
+      discard_configured_objects
+    end
+  end
+
+  def self.discard_configured_objects
+    @http_client         = nil
+    @public_key_resolver = nil unless @public_key_resolver_assigned
+    @service             = nil
   end
+  private_class_method :discard_configured_objects
 
   def self.config
     @configuration
   end
 
   def self.http_client
-    @http_client ||= KeycloakApiRails::HTTPClient.new(config, logger)
+    MONITOR.synchronize { @http_client ||= KeycloakApiRails::HTTPClient.new(config, logger) }
   end
 
   def self.public_key_resolver
-    @public_key_resolver ||= PublicKeyCachedResolver.from_configuration(http_client, config)
+    MONITOR.synchronize { @public_key_resolver ||= PublicKeyCachedResolver.from_configuration(http_client, config) }
   end
 
   # Mainly used by "keycloak-api-rails/testing" to validate tokens without a Keycloak server.
   # Assigning nil restores the regular resolver. The memoized service is discarded, since it holds
   # a reference to the resolver that is being replaced.
   def self.public_key_resolver=(resolver)
-    @public_key_resolver = resolver
-    @service             = nil
+    MONITOR.synchronize do
+      @public_key_resolver          = resolver
+      @public_key_resolver_assigned = !resolver.nil?
+      @service                      = nil
+    end
   end
 
   def self.service
-    @service ||= KeycloakApiRails::Service.new(public_key_resolver)
+    MONITOR.synchronize { @service ||= KeycloakApiRails::Service.new(public_key_resolver) }
   end
 
   def self.logger
@@ -59,6 +80,13 @@ module KeycloakApiRails
       config.token_expiration_tolerance_in_seconds  = 10
       config.public_key_cache_ttl                   = 86400
       config.custom_attributes                      = []
+      config.ca_certificate_file                    = nil
+      config.expected_audience                      = nil
+      config.expected_token_type                    = nil
+      config.verify_not_before                      = false
+      config.allow_token_in_query_string            = false
+      config.http_open_timeout                      = 5
+      config.http_read_timeout                      = 5
     end
   end