keycloak-api-rails 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23b08b9947c44a5c24411bf88b478a7042b574f9da4c18dcbc033d2b12c213f
-  data.tar.gz: c7f2b04da31060ff404dec1469d54df5e20cd8dbc91fc602047250039985d010
+  metadata.gz: 1e80ef54a212cf523766b3d1f0a4d836dd4f32c59322eb9b90a13e0e530bff08
+  data.tar.gz: c6757d2a355db048389b3c697557daea96e912eea4d2fbeea413b78bd888ce03
 SHA512:
-  metadata.gz: 8b7a27d90979f5a048f844a82def6876d42b734a6eb6af1a0ec5a99900f38c3b16009aea80c470068eb8d84fa4fd0ce671f3cddb53f853db8165f84f10808a12
-  data.tar.gz: 58408083f436a01e19fb3ba1b2efb5cbf0a8b2a1cfb793c439b33339150c39cebb5f6b499f5c83955b6d57657c7c94a9ffd932b390ee4ae830472e3d260fe26a
+  metadata.gz: 2e46089640ad0a1d9f14e08e383a5f651431f533d88e9444c809d8d4b55edc91460e668b1ff21e23e863583b4fd956056fb82b0ea9dc5e16ea34cccb268ad2cf
+  data.tar.gz: e4bfba00be03edd43b60394146bdad990b14eeb731d7e878bdf8944c00e92986278b4c11ca721fa99cd309c54289ee21e0b5199c4f357b4e614691e9d1b6b3b6

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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).
 
+## [Unreleased]
+
+### Performance
+
+* Added `# frozen_string_literal: true` to all ruby files and optimized Hot Path methods in `Service` and `Helper` (e.g., using `Regexp#match?`, avoiding redundant String-to-Symbol conversions) to significantly reduce CPU usage and memory allocations per request.
+
+### Added
+
+* Multi-tenancy support: `realm_id` can now be a String, an Array of Strings, or a Proc (e.g., `->(env) { ... }`) that evaluates to a String or Array of Strings, allowing dynamic realm resolution per request.
+* The middleware now validates the token against the allowed realms. A token carrying an `iss` claim that does not match one of the expected realms will be rejected. New `KeycloakApiRails::TokenError` reason: `:invalid_realm`.
+* `PublicKeyCachedResolver` caches public keys per-realm, ensuring safe operation in a multi-tenant environment.
+
+## [2.0.1] - 2026-08-02
+
+### Security
+
+* `skip_paths` declaring its paths as Strings, e.g. `{ get: ["/health/db"] }`, opened routes that had to be authenticated.
+* A path that is not a `Regexp` is discarded by the middleware rather than matched, and a warning is logged naming it.
+* With `verify_not_before` enabled, an `nbf` claim carried as null was read as an absent one, skipping the very check the option asks for. It is now rejected.
+* A token whose `exp` or `nbf` claim is not a number of seconds is answered a `401`, where `Time.at` used to raise a `TypeError` and answer a `500`. The 2.0.0 guard only checked that `exp` was present, not that it held a NumericDate. New `KeycloakApiRails::TokenError` reason: `:invalid_claim`.
+
+### Fixed
+
+* `custom_attributes` declared as Symbols, e.g. `[:tenant_id]`, matched no claim at all: those of a decoded token are keyed by String. Both forms are honoured.
+* `custom_attributes` holding something else than a claim name is reported by `Configuration#validate!`, instead of being silently read from no token.
+* `KeycloakApiRails.configure` discards the service, the public key resolver and the HTTP client it had memoized
+
+### Availability
+
+* A request whose token cannot be verified at all, Keycloak being unreachable and no public key having ever been retrieved, is answered a `503` carrying a `Retry-After` header. `KeycloakApiRails::HTTPError` and `KeycloakApiRails::MissingPublicKeysError` used to escape the middleware, and `keycloak_authenticate`, as a `500`: an outage of Keycloak was reported as a bug of the application. A request carrying no token at all is still answered a `401`, and the paths of `skip_paths` are still served.
+* With nothing cached, a Keycloak that is down was called again by every single request, one at a time behind the mutex of the resolver, each waiting for `http_open_timeout` and `http_read_timeout` to elapse: ten concurrent requests held ten threads for a hundred seconds. It is now called once per `FAILED_REFRESH_RETRY_DELAY_IN_SECONDS`, and the error of the last attempt is raised straight away in between.
+
 ## [2.0.0] - 2026-08-01
 
 ### Breaking changes

data/README.md

@@ -18,7 +18,7 @@ the recommended path.
 ## Install
 
 ```ruby
-gem "keycloak-api-rails", "2.0.0"
+gem "keycloak-api-rails", "2.0.2"
 ```
 
 ## Token validation
@@ -61,16 +61,16 @@ All options have a default value. However, all of them can be changed in your in
 | Option | Default Value | Type | Required? | Description  | Example |
 | ---- | ----- | ------ | ----- | ------ | ----- |
 | `server_url` | `nil`| String | Required | The base url where your Keycloak server is located. This value can be retrieved in your Keycloak client configuration. | `auth:8080` |
-| `realm_id` | `nil`| String | Required | Realm's name (not id, actually) | `master` |
+| `realm_id` | `nil`| String, Array or Proc | Required | Realm's name(s) (not id, actually). Can be a single String, an Array of Strings for multiple tenants, or a Proc for dynamic validation. | `"master"` or `["tenant1", "tenant2"]` |
 | `logger` | `Logger.new(STDOUT)`| Logger | Optional | The logger used by `keycloak-api-rails` | `Rails.logger` | 
-| `skip_paths` | `{}`| Hash of methods and paths regexp | Optional | Paths whose token must not be validated | `{ get: [/^\/health\/.+/] }`| 
+| `skip_paths` | `{}`| Hash of methods and paths regexp | Optional | Paths whose token must not be validated. Each path must be a `Regexp`. A String is refused when the application boots: `String#match` compiles its argument into a regexp, so the path of the request would become the pattern and other routes would skip authentication | `{ get: [/^\/health\/.+/] }`| 
 | `opt_in` | `false` | Boolean | Optional | When false, every request is validated by the middleware, except the ones matching `skip_paths`. When true, no middleware validates anything and authentication must be requested explicitly, by calling `keycloak_authenticate` from a controller | `true`
 | `token_expiration_tolerance_in_seconds` | `10`| Integer | Optional | Safety margin: a token is rejected this number of seconds *before* the date of its `exp` claim, so that it cannot expire in the middle of a request | `15` |
-| `public_key_cache_ttl` | `86400`| Integer | Optional | Amount of time, in seconds, specifying maximum interval between two requests to Keycloak to retrieve new public keys. It is 86400 seconds (1 day) by default. At least once per this configured interval (1 day by default) will be new public key always downloaded. | `3600` |
-| `custom_attributes` | `[]`| Array Of String | Optional | List of token attributes to read from each token and to add to their http request env | `["originalFirstName", "originalLastName"]` |
+| `public_key_cache_ttl` | `86400`| Integer | Optional | Amount of time, in seconds, specifying maximum interval between two requests to Keycloak to retrieve new public keys. It is 86400 seconds (1 day) by default. At least once per this configured interval (1 day by default) will be new public key always downloaded. The refresh happens under a lock and blocks request threads if Keycloak hangs; reducing this TTL increases the frequency of this risk. | `3600` |
+| `custom_attributes` | `[]`| Array of String or Symbol | Optional | List of token attributes to read from each token and to add to their http request env | `["originalFirstName", "originalLastName"]` |
 | `ca_certificate_file` | `nil`| String | Optional | Path to the certificate authority used to validate the Keycloak server certificate | `/credentials/production_root_ca_cert.pem` |
 | `expected_audience` | `nil`| String or Array of String | Optional | When set, a token is rejected unless its `aud` claim carries one of these audiences. Left unset, every token signed by the realm is accepted, including its ID tokens and the tokens issued for its other clients | `"my-api"` |
-| `expected_token_type` | `nil`| String | Optional | When set, a token is rejected unless its `typ` claim matches. Keycloak types its access tokens `Bearer` | `"Bearer"` |
+| `expected_token_type` | `nil`| String | Optional | When set, a token is rejected unless its `typ` claim matches (case-insensitive). Keycloak types its access tokens `Bearer` | `"Bearer"` |
 | `verify_not_before` | `false`| Boolean | Optional | When true, a token whose `nbf` claim is in the future is rejected. Disabled by default: a clock skew between Keycloak and the API would reject valid tokens | `true` |
 | `allow_token_in_query_string` | `false`| Boolean | Optional | When true, a request carrying no `Authorization` header may be authenticated by the `authorizationToken` parameter of its query string | `true` |
 | `http_open_timeout` | `5`| Integer | Optional | Seconds to wait for the connection to Keycloak to open, when downloading the public keys | `2` |
@@ -129,6 +129,27 @@ Keycloak only adds an API to the `aud` claim of a token once that API is declare
 `config.verify_not_before = true` additionally rejects a token whose `nbf` claim is in the future.
 It is disabled by default because a clock skew between Keycloak and the API rejects valid tokens.
 
+## Multi-tenancy (Multiple Realms)
+
+The library natively supports multi-tenancy by validating tokens issued by multiple Keycloak realms. 
+Instead of a static string, you can configure `realm_id` with an Array or a Proc. The library will dynamically extract the realm from the token's `iss` claim, check if it is permitted, and fetch the appropriate public keys for that specific realm.
+
+Using an Array of allowed realms:
+```ruby
+KeycloakApiRails.configure do |config|
+  config.server_url = ENV["KEYCLOAK_SERVER_URL"]
+  config.realm_id   = ["master", "tenant-1", "tenant-2"]
+end
+```
+
+Using a Proc for dynamic validation (e.g., querying the database):
+```ruby
+KeycloakApiRails.configure do |config|
+  config.server_url = ENV["KEYCLOAK_SERVER_URL"]
+  config.realm_id   = ->(realm) { Tenant.exists?(name: realm) }
+end
+```
+
 ## Use cases
 
 Once this gem is configured in your Rails project, you can read, validate and use tokens in your controllers.
@@ -212,7 +233,7 @@ For instance, to read a provided token:
 ```ruby
 class RenderTokenController < ApplicationController
   def show
-    uri     = request.env["REQUEST_URI"]
+    uri     = KeycloakApiRails::Helper.request_uri(request.env)
     headers = request.env
     token   = KeycloakApiRails.service.read_token(uri, headers)
     render json: { token: token }, status: :ok
@@ -297,13 +318,9 @@ scoped RubyGems credential.
 3. Tag the commit and push the tag:
 
 ```
-  $ git tag -a v2.0.0 -m "Version 2.0.0"
-  $ git push origin v2.0.0
+  $ git tag -a v2.0.2 -m "Version 2.0.2"
+  $ git push origin v2.0.2
 ```
 
 The workflow then checks that the tag matches `KeycloakApiRails::VERSION`, runs the tests, builds the gem
 and pushes it. It only publishes tags starting with `v`.
-
-## Next developments
-
-* Manage multiple realms

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   module Authentication
     def self.included(base)
@@ -19,6 +21,8 @@ module KeycloakApiRails
       authentication_succeeded(env, decoded_token)
     rescue TokenError => e
       authentication_failed(e.message)
+    rescue KeycloakApiRails::HTTPError, KeycloakApiRails::MissingPublicKeysError => e
+      authentication_unavailable(e)
     end
 
     def authentication_failed(message)
@@ -26,6 +30,12 @@ module KeycloakApiRails
       render status: :unauthorized, json: { error: message }
     end
 
+    def authentication_unavailable(error)
+      KeycloakApiRails.logger.error("KeycloakApiRails: no token can be verified. #{error.class}: #{error.message}")
+      response.headers["Retry-After"] = KeycloakApiRails::PublicKeyCachedResolver::FAILED_REFRESH_RETRY_DELAY_IN_SECONDS.to_s
+      render status: :service_unavailable, json: { error: "Authentication is temporarily unavailable" }
+    end
+
     def authentication_succeeded(env, decoded_token)
       Helper.assign_token(env, decoded_token, KeycloakApiRails.config.custom_attributes)
     end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class InvalidConfigurationError < StandardError; end
 
@@ -24,12 +26,11 @@ module KeycloakApiRails
       errors = []
 
       errors.push("'server_url' must be a String or nil, got #{server_url.inspect}") unless server_url.nil? || server_url.is_a?(String)
-      errors.push("'realm_id' must be a String or nil, got #{realm_id.inspect}") unless realm_id.nil? || realm_id.is_a?(String)
+      errors.push("'realm_id' must be a String, an Array of Strings, a Proc, or nil, got #{realm_id.inspect}") unless valid_realm_id?(realm_id)
       errors.push("'logger' must respond to #{LOGGER_METHODS.join(', ')}") unless LOGGER_METHODS.all? { |method| logger.respond_to?(method) }
       errors.push("'opt_in' must be true or false, got #{opt_in.inspect}") unless boolean?(opt_in)
       errors.push("'verify_not_before' must be true or false, got #{verify_not_before.inspect}") unless boolean?(verify_not_before)
       errors.push("'allow_token_in_query_string' must be true or false, got #{allow_token_in_query_string.inspect}") unless boolean?(allow_token_in_query_string)
-      errors.push("'custom_attributes' must be an Array of claim names, got #{custom_attributes.inspect}") unless custom_attributes.is_a?(Array)
       errors.push("'token_expiration_tolerance_in_seconds' must be a number of seconds, got #{token_expiration_tolerance_in_seconds.inspect}") unless number?(token_expiration_tolerance_in_seconds, allow_zero: true)
       errors.push("'public_key_cache_ttl' must be a positive number of seconds, got #{public_key_cache_ttl.inspect}") unless number?(public_key_cache_ttl)
       errors.push("'http_open_timeout' must be a positive number of seconds, got #{http_open_timeout.inspect}") unless number?(http_open_timeout)
@@ -37,6 +38,7 @@ module KeycloakApiRails
       errors.push("'expected_token_type' must be a String or nil, got #{expected_token_type.inspect}") unless expected_token_type.nil? || expected_token_type.is_a?(String)
       errors.push("'ca_certificate_file' must be the path of a readable file, got #{ca_certificate_file.inspect}") unless ca_certificate_file.nil? || File.readable?(ca_certificate_file.to_s)
 
+      errors.concat(custom_attributes_errors)
       errors.concat(skip_paths_errors)
       errors.concat(expected_audience_errors)
 
@@ -61,13 +63,26 @@ module KeycloakApiRails
 
     private
 
+    def custom_attributes_errors
+      if custom_attributes.is_a?(Array)
+        invalid_names = custom_attributes.reject { |name| name.is_a?(String) || name.is_a?(Symbol) }
+        if invalid_names.empty?
+          []
+        else
+          ["'custom_attributes' must only contain claim names, as Strings or Symbols, got #{invalid_names.inspect}"]
+        end
+      else
+        ["'custom_attributes' must be an Array of claim names, got #{custom_attributes.inspect}"] 
+      end
+    end
+
     def skip_paths_errors
       return ["'skip_paths' must be a Hash of HTTP methods and path regexps, got #{skip_paths.inspect}"] unless skip_paths.is_a?(Hash)
 
       skip_paths.filter_map do |method, paths|
-        next if paths.is_a?(Array) && paths.all? { |path| path.respond_to?(:match) }
+        next if paths.is_a?(Array) && paths.all? { |path| path.is_a?(Regexp) }
 
-        "'skip_paths[#{method.inspect}]' must be an Array of regexps, got #{paths.inspect}"
+        "'skip_paths[#{method.inspect}]' must be an Array of regexps, got #{paths.inspect}. A String is refused because 'String#match' compiles its argument into a regexp: the path of the request would become the pattern, and routes that must be authenticated would be skipped"
       end
     end
 
@@ -91,7 +106,20 @@ module KeycloakApiRails
     end
 
     def missing?(value)
-      value.nil? || value.to_s.strip.empty?
+      if value.is_a?(Array)
+        value.empty?
+      elsif value.is_a?(String)
+        value.strip.empty?
+      else
+        value.nil?
+      end
+    end
+
+    def valid_realm_id?(realm_id)
+      realm_id.nil? ||
+        realm_id.is_a?(String) ||
+        (realm_id.is_a?(Array) && realm_id.all? { |r| r.is_a?(String) }) ||
+        realm_id.respond_to?(:call)
     end
   end
 end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class Helper
 
@@ -76,15 +78,18 @@ module KeycloakApiRails
     end
 
     def self.assign_resource_roles(env, token)
-      env[RESOURCE_ROLES_KEY] = token.fetch("resource_access", {}).inject({}) do |resource_roles, (name, resource_attributes)|
+      env[RESOURCE_ROLES_KEY] = token.fetch("resource_access", {}).each_with_object({}) do |(name, resource_attributes), resource_roles|
         resource_roles[name] = resource_attributes.fetch("roles", [])
-        resource_roles
       end
     end
 
     def self.assign_current_user_custom_attributes(env, token, attribute_names)
-      names = Array(attribute_names)
-      env[CURRENT_USER_ATTRIBUTES] = token.select { |key, _value| names.include?(key) }
+      attributes = {}
+      Array(attribute_names).each do |name|
+        name_str = name.to_s
+        attributes[name_str] = token[name_str] if token.key?(name_str)
+      end
+      env[CURRENT_USER_ATTRIBUTES] = attributes
     end
 
     def self.current_user_custom_attributes(env)

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class HTTPError < StandardError
     attr_reader :status

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
 
   class Middleware
@@ -16,6 +18,9 @@ module KeycloakApiRails
         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}")
@@ -37,6 +42,13 @@ module KeycloakApiRails
       [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
       KeycloakApiRails.service
     end

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

@@ -1,49 +1,90 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class PublicKeyCachedResolver
     FAILED_REFRESH_RETRY_DELAY_IN_SECONDS = 10
 
-    attr_reader :cached_public_key_retrieved_at
+    class RealmCache
+      attr_reader :cached_public_key_retrieved_at
+
+      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?
+
+          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
+
+      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)
-      @resolver                       = PublicKeyResolver.new(http_client, realm_id)
-      @public_key_cache_ttl           = public_key_cache_ttl
-      @logger                         = logger
-      @cached_public_keys             = nil
-      @cached_public_key_retrieved_at = nil
-      @last_refresh_failure_at        = nil
-      @mutex                          = Mutex.new
+      @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
-      @mutex.synchronize do
-        refresh_public_keys if public_keys_are_outdated?
-        @cached_public_keys
-      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
 
-    private
-
-    def refresh_public_keys
-      @cached_public_keys             = @resolver.find_public_keys
-      @cached_public_key_retrieved_at = Time.now
-      @last_refresh_failure_at        = nil
-    rescue StandardError => e
-      raise if @cached_public_keys.nil?
-
-      @last_refresh_failure_at = Time.now
-      @logger&.warn("KeycloakApiRails: could not refresh the public keys (#{e.class}: #{e.message}). Keeping the ones retrieved at #{@cached_public_key_retrieved_at}.")
+    # 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
 
-    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 &&
-          (@last_refresh_failure_at.nil? ||
-            Time.now > @last_refresh_failure_at + FAILED_REFRESH_RETRY_DELAY_IN_SECONDS))
+    private
+
+    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

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

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+require 'base64'
 module KeycloakApiRails
   class MissingPublicKeysError < StandardError; end
 
@@ -6,7 +9,7 @@ module KeycloakApiRails
     def initialize(key_resolver)
       configuration                          = KeycloakApiRails.config
       @key_resolver                          = key_resolver
-      @skip_paths                            = normalize_skip_paths(configuration.skip_paths)
+      @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)
@@ -17,18 +20,52 @@ module KeycloakApiRails
 
     def decode_and_verify(token)
       raise TokenError.no_token(token) if token.nil? || token.empty?
+      
+      parts = token.to_s.split('.')
+      raise TokenError.invalid_format(token) if parts.length < 3
 
-      public_keys = @key_resolver.find_public_keys
+      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)
+      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
+        config_realm_id == realm_id
+      end
+    end
+
     def read_token(uri, headers)
       header_token = Helper.read_token_from_headers(headers)
       if !header_token.empty?
@@ -58,28 +95,50 @@ module KeycloakApiRails
       raise TokenError.unknown(token, e)
     end
 
-    def verify_claims!(token, decoded_token)
+    # 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 normalize_skip_paths(skip_paths)
+    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|
-        normalized[method.to_s.downcase.to_sym] = Array(paths)
+        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)
-      skip_paths = @skip_paths[method&.to_s&.downcase&.to_sym]
-      !skip_paths.nil? && skip_paths.any? { |skip_path| skip_path.match(path) }
+      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&.to_s&.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)

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,7 +35,7 @@ module KeycloakApiRails
         @public_keys = public_keys
       end
 
-      def find_public_keys
+      def find_public_keys(realm_id = nil)
         @public_keys
       end
     end
@@ -85,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,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   class TokenError < StandardError
     attr_reader :token, :reason, :original_error
@@ -13,10 +15,14 @@ module KeycloakApiRails
       new(token, :verification_failed, "Failed to verify JWT token", original_error)
     end
 
-    def self.invalid_format(token, original_error)
+    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
@@ -41,6 +47,10 @@ module KeycloakApiRails
       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, original_error)
       new(token, :unknown, "Failed to read JWT token", original_error)
     end

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

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

data/lib/keycloak-api-rails.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "logger"
 require "json/jwt"
 require "uri"
@@ -24,8 +26,18 @@ module KeycloakApiRails
   MONITOR = Monitor.new
 
   def self.configure
-    MONITOR.synchronize { 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
@@ -44,8 +56,9 @@ module KeycloakApiRails
   # a reference to the resolver that is being replaced.
   def self.public_key_resolver=(resolver)
     MONITOR.synchronize do
-      @public_key_resolver = resolver
-      @service             = nil
+      @public_key_resolver          = resolver
+      @public_key_resolver_assigned = !resolver.nil?
+      @service                      = nil
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-api-rails
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.2
 platform: ruby
 authors:
 - Lorent Lempereur