keycloak-api-rails 2.0.2 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e80ef54a212cf523766b3d1f0a4d836dd4f32c59322eb9b90a13e0e530bff08
-  data.tar.gz: c6757d2a355db048389b3c697557daea96e912eea4d2fbeea413b78bd888ce03
+  metadata.gz: e074e3c78c789139c8eeaf6a127dceaf0c7ff7235c1134f3fa0ea3c4149b277a
+  data.tar.gz: 6b4a5b9faaa16ab883a25c03e5eb31a0c8740f80b784812d6f47eb7aae117eb3
 SHA512:
-  metadata.gz: 2e46089640ad0a1d9f14e08e383a5f651431f533d88e9444c809d8d4b55edc91460e668b1ff21e23e863583b4fd956056fb82b0ea9dc5e16ea34cccb268ad2cf
-  data.tar.gz: e4bfba00be03edd43b60394146bdad990b14eeb731d7e878bdf8944c00e92986278b4c11ca721fa99cd309c54289ee21e0b5199c4f357b4e614691e9d1b6b3b6
+  metadata.gz: 9472f08064d6a3e3ba64b781f089d2a42861b26323f9eba3a752ec63d41e54f32288b82ed0fa1b12e46418e9c1771351c7be8676476303162e88a28d676655bd
+  data.tar.gz: 0f106f193ceaa023611b9128910b5f944ebfe213c7b7fc1237f7a2e49c55c9b76564ac84ef080e3a4c36f48bcb463da434756d00af5f370cc07a5e8842c5c0f6

data/CHANGELOG.md

@@ -5,15 +5,41 @@ 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]
+## [2.0.4] - 2026-08-03
+
+### Added
+
+* New `issuer_url` option: the `iss` claim is checked against it instead of `server_url` when set, for setups where the API reaches Keycloak through a different address than the one Keycloak advertises to its clients (e.g. an internal Docker hostname vs. a public one).
+
+## [2.0.3] - 2026-08-03
+
+### Security
+
+* The realm named by the `iss` claim is read before the signature of the token is verified, and is interpolated in the URL its public keys are downloaded from. It is now refused unless it is a plain name: the unreserved characters of RFC 3986, at most 128 of them, and not a relative path segment. `https://keycloak/realms/master?` and `https://keycloak/realms/..` both are the last segment of a well-formed `iss`, and both used to build another URL than the one of the realm they name. Such a token is answered a `401`, reason `:invalid_realm`, and no request is sent to Keycloak.
+* A token whose payload is not a JSON object, or whose `iss` claim is not a String, is answered a `401`. Reading such a payload used to raise a `NoMethodError` or a `TypeError` out of the middleware, and to be answered a `500`.
+* The number of realms whose public keys are cached is now bounded. 
+* A token was verified with whichever algorithm its `alg` header named. New `allowed_algorithms` option, defaulting to the asymmetric algorithms Keycloak signs with, and narrowable to the one of the realm. Symmetric algorithms are refused.
+
+* A `skip_paths` regexp anchored with `^` or `$` is warned about: in Ruby they match the beginning and the end of a line, and `PATH_INFO` is URL-decoded, so `"/private\n/health"` matches `/^\/health/` and skips authentication. Anchor with `\A` and `\z`.
+
+### Fixed
+
+* `base64` and `logger` are declared as runtime dependencies.
+* A `401` carries the `WWW-Authenticate: Bearer` header RFC 6750 requires of a resource protected by a Bearer token. A request carrying no token at all gets the bare challenge; any other gets `error="invalid_token"` and the reason it was refused.
 
 ### Performance
 
+* An authenticated request took four locks to read two memoized objects: `KeycloakApiRails.service`, resolved three times per request, and the per-realm key cache. They are read without locking once memoized, and the middleware resolves the service once. Worth 0.3 µs per request, against the 50 µs of the RSA verification below.
+* Every authenticated request verified the signature of its token twice: `JSON::JWT.decode` already verifies the one it is given a key for. One RSA verification per request instead of two.
 * 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.
+* CI checks the dependencies against the Ruby advisory database on every push, with `bundler-audit`, and Dependabot keeps the actions of the workflows up to date.
+* Integration tests ensuring E2E compatibility with a real Keycloak server using Docker.
+* Automated tests in CI against multiple Keycloak versions (19.0.3, 22.0.5, 25.0.0, 26.7.0).
+* Enforced that the Rake `release` task cannot be executed locally without passing the test suite first.
+* Multi-tenancy support: `realm_id` can now be a String, an Array of Strings, or a Proc (e.g. `->(realm) { Tenant.exists?(name: realm) }`) receiving the realm named by the token and answering whether it is allowed.
 * 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.
 

data/README.md

@@ -18,8 +18,7 @@ the recommended path.
 ## Install
 
 ```ruby
-gem "keycloak-api-rails", "2.0.2"
-```
+gem "keycloak-api-rails", "2.0.4"
 
 ## Token validation
 
@@ -36,7 +35,7 @@ _If both methods are used at the same time, the `Authorization` header takes pre
 
 By default, Keycloak-api-rails installs as a Rack Middleware. It processes all requests before any application logic. URIs/Paths can be excluded (opted-out) from this validation using the 'skip_paths' config option
 
-Alternatively, it can be configured to `opt-in` to validation. In this case, no Rack middleware is used, and controllers can request (opt-in) by including the module `KeycloakApiRails::Authentication` and calling `keycloak_authenticate`, for example in a `before_action`, like so: 
+Alternatively, it can be configured to `opt-in` to validation. The middleware is still installed and controllers request (opt-in) by including the module `KeycloakApiRails::Authentication` and calling `keycloak_authenticate`, for example in a `before_action`, like so: 
 
 ```ruby
 class MyApiController < ActionController::Base
@@ -60,10 +59,11 @@ 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, 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"]` |
+| `server_url` | `nil`| String | Required | The base url where your Keycloak server is located, scheme included. Without one, the url cannot be parsed and no public key is ever downloaded | `https://keycloak.example.org` or `http://auth:8080` |
+| `issuer_url` | `server_url`| String | Optional | The base url expected in a token's `iss` claim, when it differs from `server_url`. Needed when the API reaches Keycloak through a different address than the one Keycloak advertises to its clients, e.g. an internal Docker hostname vs. a public one | `https://keycloak.example.org` |
+| `realm_id` | `nil`| String, Array or Proc | Required | Realm's name(s) (not id, actually). A single String, an Array of Strings for multiple tenants, or a Proc receiving the realm named by the token and answering whether it is allowed | `"master"`, `["tenant1", "tenant2"]` or `->(realm) { Tenant.exists?(name: realm) }` |
 | `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. 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\/.+/] }`| 
+| `skip_paths` | `{}`| Hash of methods and paths regexp | Optional | Paths whose token must not be validated, matched against the URL-decoded path of the request. Each path must be a `Regexp`, anchored with `\A` and `\z`: a String is refused when the application boots, and `^` and `$` are warned about, for the reasons given below | `{ get: [/\A\/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. The refresh happens under a lock and blocks request threads if Keycloak hangs; reducing this TTL increases the frequency of this risk. | `3600` |
@@ -71,6 +71,7 @@ All options have a default value. However, all of them can be changed in your in
 | `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 (case-insensitive). Keycloak types its access tokens `Bearer` | `"Bearer"` |
+| `allowed_algorithms` | every asymmetric algorithm Keycloak signs with: `[:RS256, :RS384, :RS512, :PS256, :PS384, :PS512, :ES256, :ES384, :ES512]` | Array of String or Symbol | Optional | The algorithms a token may be signed with. Narrow it down to the one of the realm, so that the `alg` header of a token cannot pick how its own signature is verified. Symmetric algorithms are refused: a token checked against a JWKS is checked against a public key, and a key that verifies is a key that signs | `[:RS256]` |
 | `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` |
@@ -90,12 +91,19 @@ KeycloakApiRails.configure do |config|
   config.realm_id   = ENV["KEYCLOAK_REALM_ID"]
   config.logger     = Rails.logger
   config.skip_paths = {
-    post:   [/^\/message/],
-    get:    [/^\/locales/, /^\/health\/.+/]
+    post:   [/\A\/message/],
+    get:    [/\A\/locales/, /\A\/health\/.+/]
   }
 end
 ```
 
+Anchor those regexps with `\A` and `\z`, never with `^` and `$`. In Ruby, `^` and `$` match the
+beginning and the end of a *line*, not of the string. The path they are matched against is
+`PATH_INFO`, which the server has already URL-decoded, so a `%0a` in the request reaches them as a
+real newline: `"/private\n/health"` matches `/^\/health/` and skips authentication on a path that
+was never meant to be open. A regexp anchored with `^` or `$` is warned about when the first request
+is served.
+
 Or using opt-in configuration:
 
 ```ruby
@@ -129,11 +137,28 @@ 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.
 
+The `iss` claim is checked against `issuer_url`, or `server_url` when `issuer_url` is not configured, only when one of the two is set. A test environment replacing the public key resolver, as `keycloak-api-rails/testing` does, accepts any issuer.
+
+## When Keycloak is reached through a different address than its own
+
+`server_url` is used both to download public keys and, absent `issuer_url`, to check the `iss` claim. Those are two different needs: the former must be an address the API can reach, the latter must match what Keycloak put in the token, which is whatever address its own clients used. Behind a reverse proxy, or from inside Docker, these are often not the same:
+
+```ruby
+KeycloakApiRails.configure do |config|
+  config.server_url = "http://keycloak:8080"           # reachable from the API container
+  config.issuer_url = "https://keycloak.example.org"    # what Keycloak's own hostname config puts in `iss`
+  config.realm_id   = ENV["KEYCLOAK_REALM_ID"]
+end
+```
+
 ## 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.
 
+Those realms all live under the same `server_url` (or `issuer_url`, when configured): a token whose `iss` names another server is rejected, however allowed the realm it names.
+Declaring `expected_audience` matters all the more here — without it, a token issued for any client of any allowed realm opens the API.
+
 Using an Array of allowed realms:
 ```ruby
 KeycloakApiRails.configure do |config|
@@ -301,9 +326,23 @@ Assigning `KeycloakApiRails.public_key_resolver = nil` restores the regular reso
 
 From the `keycloak-rails-api` directory:
 
+```
+  $ bundle exec rspec
+```
+
+The examples of `spec/integration` are excluded: they start a Keycloak container, and without Docker
+they wait for a server that never answers. Run them, against the Keycloak version of your choice,
+with:
+
+```
+  $ KEYCLOAK_INTEGRATION=1 KEYCLOAK_VERSION=26.7.0 bundle exec rspec spec/integration
+```
+
+Or run everything in a container, which needs a Docker socket of its own to reach Keycloak:
+
 ```
   $ docker build . -t keycloak-rails-api:test
-  $ docker run -v `pwd`:/usr/src/app/ keycloak-rails-api:test bundle exec rspec spec
+  $ docker run -v `pwd`:/usr/src/app/ keycloak-rails-api:test bundle exec rspec
 ```
 
 ## How to release a new version
@@ -318,8 +357,8 @@ 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.4 -m "Version 2.0.4"
+  $ git push origin v2.0.4
 ```
 
 The workflow then checks that the tag matches `KeycloakApiRails::VERSION`, runs the tests, builds the gem

data/keycloak-api-rails.gemspec

@@ -31,10 +31,14 @@ Gem::Specification.new do |spec|
   spec.add_dependency "railties",    ">= 4.2"
   spec.add_dependency "json-jwt",    ">= 1.11.0"
 
+  spec.add_dependency "base64"
+  spec.add_dependency "logger"
+
   spec.add_development_dependency "rspec",   "3.13.2"
   spec.add_development_dependency "timecop", "0.9.11"
   spec.add_development_dependency "rails",   ">= 4.2"
   spec.add_development_dependency "rack"
   spec.add_development_dependency "rake",    ">= 13.0"
   spec.add_development_dependency "byebug", ">= 11.1.3"
+  spec.add_development_dependency "bundler-audit", ">= 0.9"
 end

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

@@ -16,10 +16,12 @@ module KeycloakApiRails
       path   = env["PATH_INFO"]
 
       KeycloakApiRails.logger.debug("Start authentication for #{method} : #{path}")
-      token         = KeycloakApiRails.service.read_token(Helper.request_uri(env), env)
-      decoded_token = KeycloakApiRails.service.decode_and_verify(token)
+      service       = KeycloakApiRails.service
+      token         = service.read_token(Helper.request_uri(env), env)
+      decoded_token = service.decode_and_verify(token)
       authentication_succeeded(env, decoded_token)
     rescue TokenError => e
+      response.headers["WWW-Authenticate"] = e.challenge
       authentication_failed(e.message)
     rescue KeycloakApiRails::HTTPError, KeycloakApiRails::MissingPublicKeysError => e
       authentication_unavailable(e)

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

@@ -7,6 +7,7 @@ module KeycloakApiRails
     LOGGER_METHODS = [:debug, :info, :warn, :error].freeze
 
     attr_accessor :server_url
+    attr_accessor :issuer_url
     attr_accessor :realm_id
     attr_accessor :skip_paths
     attr_accessor :opt_in
@@ -21,11 +22,13 @@ module KeycloakApiRails
     attr_accessor :allow_token_in_query_string
     attr_accessor :http_open_timeout
     attr_accessor :http_read_timeout
+    attr_accessor :allowed_algorithms
 
     def validate!
       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("'issuer_url' must be a String or nil, got #{issuer_url.inspect}") unless issuer_url.nil? || issuer_url.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)
@@ -41,6 +44,7 @@ module KeycloakApiRails
       errors.concat(custom_attributes_errors)
       errors.concat(skip_paths_errors)
       errors.concat(expected_audience_errors)
+      errors.concat(allowed_algorithms_errors)
 
       raise InvalidConfigurationError, "Invalid Keycloak configuration: #{errors.join('; ')}" unless errors.empty?
 
@@ -97,6 +101,19 @@ module KeycloakApiRails
       end
     end
 
+    def allowed_algorithms_errors
+      unless allowed_algorithms.is_a?(Array) && !allowed_algorithms.empty?
+        return ["'allowed_algorithms' must be a non-empty Array of algorithm names, got #{allowed_algorithms.inspect}"]
+      end
+
+      unsupported = allowed_algorithms.reject { |algorithm| Service::SUPPORTED_ALGORITHMS.include?(algorithm.to_s.to_sym) }
+      if unsupported.empty?
+        []
+      else
+        ["'allowed_algorithms' declares #{unsupported.inspect}, which this library does not verify. It accepts #{Service::SUPPORTED_ALGORITHMS.inspect}"]
+      end
+    end
+
     def boolean?(value)
       value == true || value == false
     end

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

@@ -8,16 +8,17 @@ module KeycloakApiRails
     end
 
     def call(env)
-      method = env["REQUEST_METHOD"]
-      path   = env["PATH_INFO"]
+      method  = env["REQUEST_METHOD"]
+      path    = env["PATH_INFO"]
+      service = KeycloakApiRails.service
 
       if service.need_middleware_authentication?(method, path, env)
         logger.debug("Start authentication for #{method} : #{path}")
         begin
-          authenticate(env)
+          authenticate(service, env)
         rescue TokenError => e
           logger.debug("The error causing the Token to fail: #{e.original_error&.message || e.message}")
-          return authentication_failed(e.message)
+          return authentication_failed(e)
         rescue HTTPError, MissingPublicKeysError => e
           logger.error("KeycloakApiRails: no token can be verified for #{method} : #{path}. #{e.class}: #{e.message}")
           return authentication_unavailable
@@ -31,15 +32,18 @@ module KeycloakApiRails
 
     private
 
-    def authenticate(env)
+    def authenticate(service, 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)
+    def authentication_failed(error)
       # Rack 3 requires header names to be lowercase.
-      [401, { "content-type" => "application/json" }, [{ error: message }.to_json]]
+      [401,
+       { "content-type"     => "application/json",
+         "www-authenticate" => error.challenge },
+       [{ error: error.message }.to_json]]
     end
 
     def authentication_unavailable
@@ -49,10 +53,6 @@ module KeycloakApiRails
        [{ error: "Authentication is temporarily unavailable" }.to_json]]
     end
 
-    def service
-      KeycloakApiRails.service
-    end
-
     def logger
       KeycloakApiRails.logger
     end

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

@@ -3,6 +3,7 @@
 module KeycloakApiRails
   class PublicKeyCachedResolver
     FAILED_REFRESH_RETRY_DELAY_IN_SECONDS = 10
+    MAX_CACHED_REALMS                     = 64
 
     class RealmCache
       attr_reader :cached_public_key_retrieved_at
@@ -58,10 +59,12 @@ module KeycloakApiRails
     def initialize(http_client, realm_id, public_key_cache_ttl, logger = nil)
       @http_client          = http_client
       @realm_id             = realm_id
+      @configured_realms    = configured_realms(realm_id)
       @public_key_cache_ttl = public_key_cache_ttl
       @logger               = logger
       @caches               = {}
       @caches_mutex         = Mutex.new
+      @refusal_logged       = false
     end
 
     def self.from_configuration(http_client, configuration)
@@ -69,22 +72,49 @@ module KeycloakApiRails
     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)
+      cache_for(realm_id || default_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
+      cache_for(realm_id || default_realm).cached_public_key_retrieved_at
     end
 
     private
 
+    def default_realm
+      @realm_id if @realm_id.is_a?(String)
+    end
+
+    def configured_realms(realm_id)
+      case realm_id
+      when String then [realm_id].freeze
+      when Array  then realm_id.dup.freeze
+      end
+    end
+
     def cache_for(realm_id)
-      @caches_mutex.synchronize do
-        @caches[realm_id] ||= RealmCache.new(@http_client, realm_id)
+      @caches[realm_id] || @caches_mutex.synchronize { @caches[realm_id] || create_cache(realm_id) }
+    end
+
+    def create_cache(realm_id)
+      refuse(realm_id, "it is not one of the configured realms")         unless cacheable?(realm_id)
+      refuse(realm_id, "#{MAX_CACHED_REALMS} realms are already cached") if     @caches.size >= MAX_CACHED_REALMS
+
+      @caches[realm_id] = RealmCache.new(@http_client, realm_id)
+    end
+
+    def cacheable?(realm_id)
+      !realm_id.nil? && (@configured_realms.nil? || @configured_realms.include?(realm_id))
+    end
+
+    def refuse(realm_id, reason)
+      unless @refusal_logged
+        @refusal_logged = true
+        @logger&.warn("KeycloakApiRails: no public key is downloaded for the realm #{realm_id.inspect}, #{reason}. The requests naming it are answered a 503. Further refusals are not logged.")
       end
+
+      raise MissingPublicKeysError, "No Keycloak public key can be downloaded for the realm #{realm_id.inspect}"
     end
   end
 end

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

@@ -5,6 +5,8 @@ module KeycloakApiRails
   class MissingPublicKeysError < StandardError; end
 
   class Service
+    REALM_NAME = /\A(?!\.+\z)[A-Za-z0-9._~-]{1,128}\z/.freeze
+    SUPPORTED_ALGORITHMS = %i[RS256 RS384 RS512 PS256 PS384 PS512 ES256 ES384 ES512].freeze
 
     def initialize(key_resolver)
       configuration                          = KeycloakApiRails.config
@@ -16,6 +18,7 @@ module KeycloakApiRails
       @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
+      @allowed_algorithms                    = Array(configuration.allowed_algorithms).map(&:to_sym)
     end
 
     def decode_and_verify(token)
@@ -43,11 +46,21 @@ module KeycloakApiRails
       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
+      parsed_payload  = JSON.parse(decoded_payload)
+
+      if parsed_payload.is_a?(Hash)
+        iss = parsed_payload['iss']
+        return nil unless iss.is_a?(String)
+  
+        realm_id = iss.split('/').last
+        if realm_id&.match?(REALM_NAME)
+          realm_id 
+        else
+          nil
+        end
+      else
+        nil
+      end
     rescue JSON::ParserError, ArgumentError
       nil
     end
@@ -84,9 +97,7 @@ module KeycloakApiRails
     private
 
     def decode(token, public_keys)
-      decoded_token = JSON::JWT.decode(token, public_keys)
-      decoded_token.verify!(public_keys)
-      decoded_token
+      JSON::JWT.decode(token, public_keys, @allowed_algorithms)
     rescue JSON::JWT::VerificationFailed, JSON::JWK::Set::KidNotFound => e
       raise TokenError.verification_failed(token, e)
     rescue JSON::JWT::InvalidFormat => e
@@ -105,8 +116,9 @@ module KeycloakApiRails
       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)
+      issuer_url = KeycloakApiRails.config.issuer_url || KeycloakApiRails.config.server_url
+      if issuer_url
+        expected_iss = File.join(issuer_url.to_s, "realms", realm_id.to_s)
         raise TokenError.invalid_realm(token) unless decoded_token["iss"] == expected_iss
       end
     end
@@ -128,10 +140,20 @@ module KeycloakApiRails
           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
 
+        line_anchored = regexps.select { |regexp| line_anchored?(regexp) }
+        unless line_anchored.empty?
+          logger&.warn("KeycloakApiRails: 'skip_paths[#{method.inspect}]' declares #{line_anchored.map(&:inspect).join(', ')}, anchored with '^' or '$'. In Ruby those match the beginning and the end of a line, not of the path: \"/private\\n/health\" matches /^\\/health/ and skips authentication. Anchor with '\\A' and '\\z'.")
+        end
+
         normalized[method.to_s.upcase] = regexps
       end
     end
 
+    # Escaped pairs are dropped first, so that '\^' does not count and '[^/]' is read as a class.
+    def line_anchored?(regexp)
+      regexp.source.gsub(/\\./, "").gsub(/\[[^\]]*\]/, "").match?(/[\^$]/)
+    end
+
     def should_skip?(method, path)
       skip_paths = @skip_paths[method]
       !skip_paths.nil? && skip_paths.any? { |skip_path| skip_path.match?(path) }

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

@@ -90,7 +90,8 @@ module KeycloakApiRails
         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)
+          issuer_url = KeycloakApiRails.config.issuer_url || KeycloakApiRails.config.server_url
+          payload["iss"] = File.join(issuer_url.to_s, "realms", realm_id)
         end
 
         claims.each { |name, value| payload[name.to_s] = value }

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

@@ -11,6 +11,15 @@ module KeycloakApiRails
       @original_error = original_error
     end
 
+    # RFC 6750: a request that carried no credentials at all gets the bare challenge, no error code.
+    def challenge
+      if reason == :no_token
+        "Bearer"
+      else
+        %(Bearer error="invalid_token", error_description="#{message.gsub(/["\\]/, '')}")
+      end
+    end
+
     def self.verification_failed(token, original_error)
       new(token, :verification_failed, "Failed to verify JWT token", original_error)
     end

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

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

data/lib/keycloak-api-rails.rb

@@ -23,6 +23,11 @@ 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'.
+  #
+  # Once memoized they are read without taking it: the assignment publishes an object that is fully
+  # built, and MRI reads an instance variable atomically. A 'configure' running while requests are
+  # already being served may then be picked up one request late, which is one more reason for it to
+  # belong in an initializer.
   MONITOR = Monitor.new
 
   def self.configure
@@ -44,11 +49,11 @@ module KeycloakApiRails
   end
 
   def self.http_client
-    MONITOR.synchronize { @http_client ||= KeycloakApiRails::HTTPClient.new(config, logger) }
+    @http_client || MONITOR.synchronize { @http_client ||= KeycloakApiRails::HTTPClient.new(config, logger) }
   end
 
   def self.public_key_resolver
-    MONITOR.synchronize { @public_key_resolver ||= PublicKeyCachedResolver.from_configuration(http_client, config) }
+    @public_key_resolver || 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.
@@ -63,7 +68,7 @@ module KeycloakApiRails
   end
 
   def self.service
-    MONITOR.synchronize { @service ||= KeycloakApiRails::Service.new(public_key_resolver) }
+    @service || MONITOR.synchronize { @service ||= KeycloakApiRails::Service.new(public_key_resolver) }
   end
 
   def self.logger
@@ -73,6 +78,7 @@ module KeycloakApiRails
   def self.load_configuration
     configure do |config|
       config.server_url                             = nil
+      config.issuer_url                             = nil
       config.realm_id                               = nil
       config.logger                                 = ::Logger.new(STDOUT)
       config.skip_paths                             = {}
@@ -87,6 +93,7 @@ module KeycloakApiRails
       config.allow_token_in_query_string            = false
       config.http_open_timeout                      = 5
       config.http_read_timeout                      = 5
+      config.allowed_algorithms                     = KeycloakApiRails::Service::SUPPORTED_ALGORITHMS
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-api-rails
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.4
 platform: ruby
 authors:
 - Lorent Lempereur
@@ -37,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.11.0
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +149,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 11.1.3
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Rack middleware that validates the Keycloak JWT access token carried
   by every request of a Ruby on Rails API. It verifies the token signature against
   the realm public keys, exposes the authenticated user, its roles and the custom