keycloak-api-rails 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74dec51fa027308c2cf5b57ca67b7316b21677bf1592022f76988f232bbde911
-  data.tar.gz: 4836a7951bbf1559ff5eec0dfeb004ff8bcd2955cee7e06ee9e8a553743ad99e
+  metadata.gz: b23b08b9947c44a5c24411bf88b478a7042b574f9da4c18dcbc033d2b12c213f
+  data.tar.gz: c7f2b04da31060ff404dec1469d54df5e20cd8dbc91fc602047250039985d010
 SHA512:
-  metadata.gz: 48b3307f4dff316dfa063deddf0d106bbcc409856c20f0af5c441bdc3b1163e9cf93f0c3f7e53fd1a90fcb7946744c2b1b8863fd5a61a0c4012fe3d7df6b5aee
-  data.tar.gz: 81aca7224bcae644dd35f6fb715bdb447b0da549bc3da0bdd311a6bea06adfba468936aabcdaeb305a44839c6770a46644abfdf81f2f828246414880e9ab52dd
+  metadata.gz: 8b7a27d90979f5a048f844a82def6876d42b734a6eb6af1a0ec5a99900f38c3b16009aea80c470068eb8d84fa4fd0ce671f3cddb53f853db8165f84f10808a12
+  data.tar.gz: 58408083f436a01e19fb3ba1b2efb5cbf0a8b2a1cfb793c439b33339150c39cebb5f6b499f5c83955b6d57657c7c94a9ffd932b390ee4ae830472e3d260fe26a

data/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-08-01
+
+### Breaking changes
+
+* `TokenError` is now namespaced: `KeycloakApiRails::TokenError`.
+* The gem depends on `railties` rather than on the whole `rails` meta gem
+* An invalid configuration raises `KeycloakApiRails::InvalidConfigurationError` when the application boots
+* A token this library cannot read at all is answered a `401`, where an unexpected error used to escape the middleware as a `500`
+* A token carried by the `authorizationToken` query string parameter is ignored unless the new `allow_token_in_query_string` option is enabled
+* `KeycloakApiRails::HTTPClient` raises `KeycloakApiRails::HTTPError` when Keycloak answers an error, a malformed payload, or cannot be reached.
+
+### Security
+
+* New `expected_audience` option: when set, a token whose `aud` claim does not carry one of the expected audiences is rejected. Without it, every token signed by the realm is accepted (including its ID tokens) which Keycloak signs with the very same key, and the access tokens issued for its other clients
+* New `expected_token_type` option: when set, a token whose `typ` claim does not match is rejected. Keycloak types its access tokens `Bearer`
+* New `verify_not_before` option: when enabled, a token whose `nbf` claim is in the future is rejected. Disabled by default, since a clock skew between Keycloak and the API would reject valid tokens
+* A token carrying no `exp` claim is rejected, where `Time.at(nil)` used to raise a `TypeError` and answer a `500`
+* The resolver never answers without a public key: decoding a token without one would skip the signature verification altogether
+
+### Fixed
+
+* The `401` answered by the middleware carries a lowercase `content-type` header, as the Rack 3 SPEC requires.
+* The `Authorization` header is read again when the Rack environment carries no `REQUEST_URI`. 
+* A `TokenError` raised further down the stack is no longer swallowed by the middleware and turned into a `401`
+* `skip_paths` declared with String or upcased HTTP methods, e.g. `{ "GET" => [...] }`, are honoured instead of silently never matching
+* `TokenError.unknown` raised an `ArgumentError`, being called without any argument
+* `TokenError.invalid_format` no longer reports a `nil` cause: the rescue clause read an `e` that was never bound
+* `Helper.current_user_roles` was declared twice
+* The `Authorization` scheme is read case-insensitively, as RFC 7235 requires, and any amount of whitespace may separate it from the token. `gsub(/^Bearer /, "")` also stripped the scheme from every line that followed the first one, `^` matching the beginning of any line in Ruby
+
+### Thread safety
+
+* The memoized service, public key resolver and HTTP client are built once per process, whichever thread reaches them first. Every thread of a threaded server used to build its own on the first request
+* The public keys are downloaded once when several threads find the cache expired at the same time, rather than once per thread
+* `KeycloakApiRails::Testing` generates a single key pair under a parallelized test suite. Two threads generating one each would leave the signing key and the published public key out of sync, failing the verification of every forged token
+
+### Availability
+
+* The requests downloading the public keys apply the new `http_open_timeout` and `http_read_timeout` options, 5 seconds each. Without them, `Net::HTTP` waits 60 seconds to open the connection and 60 more to read the answer: a Keycloak that hangs held every request thread of the API
+* An unreachable Keycloak no longer takes the API down: the public keys retrieved last keep being used past their TTL, and a failed refresh is not attempted again for 10 seconds
+
+### Added
+
+* The configuration is validated at boot, and `Configuration#validate!` reports every problem at once
+* A warning is logged at boot when `server_url` and `realm_id` are not both configured
+
+### Upgrading from 1.x to 2.0
+
+* `TokenError` has moved into the module of the library, and is now `KeycloakApiRails::TokenError`. An application rescuing it (typically around `keycloak_authenticate`) has to be updated. Its `reason` can now also be `:not_yet_valid`, `:invalid_audience`, `:invalid_token_type`, `:missing_claim` and `:unknown`
+* A token carried by the `authorizationToken` query string parameter is ignored unless `config.allow_token_in_query_string = true` is set, and the `Authorization` header now takes precedence over it. An API whose clients pass their token through the URL (a browser following a link, a `<video>` tag) has to enable the option explicitly.
+* The gem depends on `railties` instead of `rails`. An application that relied on this gem to pull Rails in has to declare `rails` itself
+* A configuration mistake now raises a `KeycloakApiRails::InvalidConfigurationError` when the application boots, instead of failing on the first request
+* A request carrying a token that this library cannot read at all is answered a `401` instead of raising, which used to result in a `500`
+* Failing to download the public keys raises a `KeycloakApiRails::HTTPError`. It used to log the error and let the resolver fail later, with an unrelated `NoMethodError`
+
 ## [1.1.2] - 2026-08-01
 
 * Gem metadata

data/README.md

@@ -5,7 +5,7 @@ This gem validates Keycloak JWT token for Ruby On Rails APIs.
 ## Requirements
 
 * Ruby `>= 2.7`
-* Rails `>= 4.2`
+* Railties `>= 4.2` — only `Rails::Railtie` is used
 
 Every push is tested against Ruby 2.7, 3.0, 3.1, 3.2, 3.3, 3.4 and 4.0. Each of them installs the
 most recent dependencies it supports, so the test suite runs against Rails 7.1 (Ruby 2.7 and 3.0),
@@ -18,27 +18,25 @@ the recommended path.
 ## Install
 
 ```ruby
-gem "keycloak-api-rails", "1.1.2"
+gem "keycloak-api-rails", "2.0.0"
 ```
 
 ## Token validation
 
-Tokens sent (through query strings or Authorization headers) are validated against a Keycloak public key. This public key is downloaded every day by default (this interval can be changed through `public_key_cache_ttl`).
+Tokens are validated against a Keycloak public key. This public key is downloaded every day by default (this interval can be changed through `public_key_cache_ttl`).
 
 ## Pass token to the API
 
-* Method 1: By adding an `Authorization` HTTP Header with its value set to `Bearer <your token>`.
-  _e.g_ using curl: `curl -H "Authorization: Bearer <your-token>" https://api.pouet.io/api/more-pouets`
-* Method 2: By providing the token via query string, especially via the parameter named `authorizationToken`. Keep in mind that this method is less secure (url are kept intact in your browser history, and so on...)
-  _e.g._ using curl: `curl https://api.pouet.io/api/more-pouets?authorizationToken<your-token>`
+* Method 1: By adding an `Authorization` HTTP Header with its value set to `Bearer <your token>`. The scheme is case-insensitive.  _e.g_ using curl: `curl -H "Authorization: Bearer <your-token>" https://api.pouet.io/api/more-pouets`
+* Method 2: By providing the token via query string, in the parameter named `authorizationToken`. This method has to be enabled explicitly, through `config.allow_token_in_query_string = true`: a token carried by a URL is kept in the browser history, sent along in the `Referer` header, and written to the access logs of every proxy on the way. _e.g._ using curl: `curl https://api.pouet.io/api/more-pouets?authorizationToken=<your-token>`
 
-_If both method are used at the same time, The query string as a higher priority when reading given tokens._
+_If both methods are used at the same time, the `Authorization` header takes precedence: it is the one that does not leak._
 
 ## Opt-in vs. Opt-out validation
 
 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. 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: 
 
 ```ruby
 class MyApiController < ActionController::Base
@@ -62,15 +60,26 @@ 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` |
+| `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` |
-| `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 the token must not be validatefd | `{ get: [/^\/health\/.+/] }`| 
-| `opt_in` | `false` | Boolean | Optional | When true, All requests will be validated (excluding requests matching `skip_paths`). When false, validation must be explicitly requested | `true`
-| `token_expiration_tolerance_in_seconds` | `10`| Logger | Optional | Number of seconds a token can expire before being rejected by the API. | `15` | 
-| `public_key_cache_ttl` | `86400`| Integer | Optional | Amount of time, in seconds, specifying maximum interval between two requests to {project_name} 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. | `Rails.logger` | 
-| `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"]` | 
-| `ca_certificate_file` | `nil`| String | Optional | Path to the certificate authority used to validate the Keycloak server certificate | `/credentials/production_root_ca_cert.pem` | 
+| `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\/.+/] }`| 
+| `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"]` |
+| `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"` |
+| `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` |
+| `http_read_timeout` | `5`| Integer | Optional | Seconds to wait for the answer of Keycloak, when downloading the public keys | `2` |
+
+The configuration is validated when the application boots: a mistake in the initializer raises a
+`KeycloakApiRails::InvalidConfigurationError` naming the offending option, rather than failing on
+the first request that reaches the middleware.
+
 ## Configure it
 
 Create a `keycloak.rb` file in your Rails `config/initializers` folder. For instance:
@@ -100,6 +109,26 @@ end
 
 When using `opt-in` is true, `skip_paths` is not used. 
 
+## Restricting which tokens are accepted
+
+A token is always checked against the public keys of the realm, and against its expiration date.
+That alone accepts *every* token the realm signed: the ID token of the same user, and the access tokens issued for the other clients of that realm. Declaring the audience the API expects.
+The `aud` claim, and the type of token it accepts, the `typ` claim, which Keycloak sets to `Bearer` on its access tokens, narrows that down:
+
+```ruby
+KeycloakApiRails.configure do |config|
+  config.server_url          = ENV["KEYCLOAK_SERVER_URL"]
+  config.realm_id            = ENV["KEYCLOAK_REALM_ID"]
+  config.expected_audience   = "my-api"
+  config.expected_token_type = "Bearer"
+end
+```
+
+Keycloak only adds an API to the `aud` claim of a token once that API is declared as an audience of the client requesting it, through an *audience mapper* on the client scope. Check what your realm actually issues before enabling `expected_audience`, or every request will be answered a `401`.
+
+`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.
+
 ## Use cases
 
 Once this gem is configured in your Rails project, you can read, validate and use tokens in your controllers.
@@ -173,6 +202,8 @@ end
 
 This should output `https://api.pouet.io/api/more-pouets?authorizationToken=myToken`.
 
+Such an URL is only accepted by an API that set `config.allow_token_in_query_string = true`.
+
 
 ### Accessing Keycloak Service
 
@@ -266,8 +297,8 @@ scoped RubyGems credential.
 3. Tag the commit and push the tag:
 
 ```
-  $ git tag -a v1.2.0 -m "Version 1.2.0"
-  $ git push origin v1.2.0
+  $ git tag -a v2.0.0 -m "Version 2.0.0"
+  $ git push origin v2.0.0
 ```
 
 The workflow then checks that the tag matches `KeycloakApiRails::VERSION`, runs the tests, builds the gem
@@ -275,5 +306,4 @@ and pushes it. It only publishes tags starting with `v`.
 
 ## Next developments
 
-* Manage multiple realms
-* Avoid duplicate code in KeycloakApiRails::Middleware and `KeycloakApiRails::Authentication`
+* Manage multiple realms

data/keycloak-api-rails.gemspec

@@ -28,14 +28,13 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 2.7"
 
-  spec.add_dependency "rails",       ">= 4.2"
+  spec.add_dependency "railties",    ">= 4.2"
   spec.add_dependency "json-jwt",    ">= 1.11.0"
 
   spec.add_development_dependency "rspec",   "3.13.2"
   spec.add_development_dependency "timecop", "0.9.11"
-  # Required by 'rake release', which builds and publishes the gem from the CI.
+  spec.add_development_dependency "rails",   ">= 4.2"
+  spec.add_development_dependency "rack"
   spec.add_development_dependency "rake",    ">= 13.0"
-  # Not pinned to an exact version: byebug 12 requires Ruby >= 3.1, byebug 13 requires Ruby >= 3.2.
-  # Older Rubies resolve to byebug 11.
   spec.add_development_dependency "byebug", ">= 11.1.3"
 end

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

@@ -9,13 +9,12 @@ module KeycloakApiRails
     protected
 
     def keycloak_authenticate
-      env = request.env
+      env    = request.env
       method = env["REQUEST_METHOD"]
       path   = env["PATH_INFO"]
-      uri    = env["REQUEST_URI"]
 
       KeycloakApiRails.logger.debug("Start authentication for #{method} : #{path}")
-      token         = KeycloakApiRails.service.read_token(uri, env)
+      token         = KeycloakApiRails.service.read_token(Helper.request_uri(env), env)
       decoded_token = KeycloakApiRails.service.decode_and_verify(token)
       authentication_succeeded(env, decoded_token)
     rescue TokenError => e
@@ -28,14 +27,7 @@ module KeycloakApiRails
     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, KeycloakApiRails.config.custom_attributes)
-      Helper.assign_realm_roles(env, decoded_token)
-      Helper.assign_resource_roles(env, decoded_token)
-      Helper.assign_keycloak_token(env, decoded_token)
+      Helper.assign_token(env, decoded_token, KeycloakApiRails.config.custom_attributes)
     end
   end
 end

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

@@ -1,5 +1,9 @@
 module KeycloakApiRails
+  class InvalidConfigurationError < StandardError; end
+
   class Configuration
+    LOGGER_METHODS = [:debug, :info, :warn, :error].freeze
+
     attr_accessor :server_url
     attr_accessor :realm_id
     attr_accessor :skip_paths
@@ -9,5 +13,85 @@ module KeycloakApiRails
     attr_accessor :custom_attributes
     attr_accessor :logger
     attr_accessor :ca_certificate_file
+    attr_accessor :expected_audience
+    attr_accessor :expected_token_type
+    attr_accessor :verify_not_before
+    attr_accessor :allow_token_in_query_string
+    attr_accessor :http_open_timeout
+    attr_accessor :http_read_timeout
+
+    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("'realm_id' must be a String or nil, got #{realm_id.inspect}") unless realm_id.nil? || realm_id.is_a?(String)
+      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)
+      errors.push("'http_read_timeout' must be a positive number of seconds, got #{http_read_timeout.inspect}") unless number?(http_read_timeout)
+      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(skip_paths_errors)
+      errors.concat(expected_audience_errors)
+
+      raise InvalidConfigurationError, "Invalid Keycloak configuration: #{errors.join('; ')}" unless errors.empty?
+
+      true
+    end
+
+    def validate_server!
+      errors = []
+      errors.push("'server_url' must be configured, e.g. 'https://keycloak.example.org'") if missing?(server_url)
+      errors.push("'realm_id' must be configured, e.g. 'master'") if missing?(realm_id)
+
+      raise InvalidConfigurationError, "Invalid Keycloak configuration: #{errors.join('; ')}" unless errors.empty?
+
+      true
+    end
+
+    def server_configured?
+      !missing?(server_url) && !missing?(realm_id)
+    end
+
+    private
+
+    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) }
+
+        "'skip_paths[#{method.inspect}]' must be an Array of regexps, got #{paths.inspect}"
+      end
+    end
+
+    def expected_audience_errors
+      case expected_audience
+      when nil, String
+        []
+      when Array
+        expected_audience.all? { |audience| audience.is_a?(String) } ? [] : ["'expected_audience' must only contain Strings, got #{expected_audience.inspect}"]
+      else
+        ["'expected_audience' must be a String, an Array of Strings, or nil, got #{expected_audience.inspect}"]
+      end
+    end
+
+    def boolean?(value)
+      value == true || value == false
+    end
+
+    def number?(value, allow_zero: false)
+      value.is_a?(Numeric) && (allow_zero ? value >= 0 : value > 0)
+    end
+
+    def missing?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
   end
 end

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

@@ -10,6 +10,18 @@ module KeycloakApiRails
     RESOURCE_ROLES_KEY           = "keycloak:resource_roles"
     TOKEN_KEY                    = "keycloak:token"
     QUERY_STRING_TOKEN_KEY       = "authorizationToken"
+    BEARER_PREFIX                = /\ABearer[[:space:]]+/i.freeze # RFC 7235 makes the authentication scheme case-insensitive.
+
+    def self.assign_token(env, token, custom_attribute_names)
+      assign_current_user_id(env, token)
+      assign_current_authorized_party(env, token)
+      assign_current_user_email(env, token)
+      assign_current_user_locale(env, token)
+      assign_current_user_custom_attributes(env, token, custom_attribute_names)
+      assign_realm_roles(env, token)
+      assign_resource_roles(env, token)
+      assign_keycloak_token(env, token)
+    end
 
     def self.current_user_id(env)
       env[CURRENT_USER_ID_KEY]
@@ -71,15 +83,23 @@ module KeycloakApiRails
     end
 
     def self.assign_current_user_custom_attributes(env, token, attribute_names)
-      env[CURRENT_USER_ATTRIBUTES] = token.select { |key, value| attribute_names.include?(key) }
+      names = Array(attribute_names)
+      env[CURRENT_USER_ATTRIBUTES] = token.select { |key, _value| names.include?(key) }
     end
 
     def self.current_user_custom_attributes(env)
       env[CURRENT_USER_ATTRIBUTES]
     end
 
-    def self.current_user_roles(env)
-      env[ROLES_KEY]
+    def self.request_uri(env)
+      # 'REQUEST_URI' is not part of the Rack spec: Puma and Unicorn do set it
+      if env["REQUEST_URI"].nil?
+        query_string = env["QUERY_STRING"]
+        path         = env["PATH_INFO"].to_s
+        query_string.nil? || query_string.empty? ? path : "#{path}?#{query_string}"
+      else
+        env["REQUEST_URI"]
+      end
     end
 
     def self.read_token_from_query_string(uri)
@@ -91,6 +111,8 @@ module KeycloakApiRails
       else
         ""
       end
+    rescue URI::InvalidURIError, ArgumentError
+      nil
     end
 
     def self.create_url_with_token(uri, token)
@@ -102,7 +124,12 @@ module KeycloakApiRails
     end
 
     def self.read_token_from_headers(headers)
-      headers["HTTP_AUTHORIZATION"]&.gsub(/^Bearer /, "") || ""
+      authorization = headers["HTTP_AUTHORIZATION"]
+      if authorization.nil?
+        ""
+      else
+        authorization.sub(BEARER_PREFIX, "")
+      end
     end
   end
 end

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

@@ -1,35 +1,70 @@
 module KeycloakApiRails
+  class HTTPError < StandardError
+    attr_reader :status
+
+    def initialize(message, status = nil)
+      super(message)
+      @status = status
+    end
+  end
+
   class HTTPClient
+    UNREACHABLE_ERRORS = [
+      Timeout::Error,
+      SocketError,
+      SystemCallError,
+      IOError,
+      OpenSSL::SSL::SSLError,
+      Net::ProtocolError
+    ].freeze
+
     def initialize(configuration, logger)
-      @server_url          = configuration.server_url
-      @ca_certificate_file = configuration.ca_certificate_file
-      @logger              = logger
-      @x509_store          = OpenSSL::X509::Store.new
+      @configuration = configuration
+      @logger        = logger
+      @x509_store    = OpenSSL::X509::Store.new
       @x509_store.set_default_paths
-      @x509_store.add_file(@ca_certificate_file) if @ca_certificate_file
+      @x509_store.add_file(configuration.ca_certificate_file) if configuration.ca_certificate_file
     end
 
     def get(realm_id, path)
-      uri          = build_uri(realm_id, path)
-      use_ssl      = uri.scheme == "http" ? false : true
-      Net::HTTP.start(uri.host, uri.port, :use_ssl => use_ssl, :cert_store => @x509_store) do |http|
-        request  = Net::HTTP::Get.new(uri)
-        response = http.request(request)
-        
-        begin
-          response.value
-          JSON.parse(response.body)
-        rescue
-          @logger.error("KeycloakApiRails responded with an error when calling '#{path}'. Status #{response.code}. Payload: #{response.body}")
-        end
+      @configuration.validate_server!
+
+      uri      = build_uri(realm_id, path)
+      response = request(uri)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        @logger.error("KeycloakApiRails: Keycloak responded with an error when calling '#{path}'. Status #{response.code}. Payload: #{response.body}")
+        raise HTTPError.new("Keycloak responded with a #{response.code} status when calling '#{path}'", response.code)
       end
+
+      parse(response, path)
     end
 
     private
 
+    def request(uri)
+      Net::HTTP.start(uri.host,
+                      uri.port,
+                      use_ssl:      uri.scheme != "http",
+                      cert_store:   @x509_store,
+                      open_timeout: @configuration.http_open_timeout,
+                      read_timeout: @configuration.http_read_timeout) do |http|
+        http.request(Net::HTTP::Get.new(uri))
+      end
+    rescue *UNREACHABLE_ERRORS => e
+      @logger.error("KeycloakApiRails: could not reach Keycloak at '#{uri}'. #{e.class}: #{e.message}")
+      raise HTTPError, "Could not reach Keycloak at '#{uri}': #{e.message}"
+    end
+
+    def parse(response, path)
+      JSON.parse(response.body)
+    rescue JSON::ParserError => e
+      @logger.error("KeycloakApiRails: could not parse the response of '#{path}'. #{e.message}")
+      raise HTTPError, "Keycloak returned a malformed JSON payload when calling '#{path}'"
+    end
+
     def build_uri(realm_id, path)
-      string_uri = File.join(@server_url, "realms", realm_id, path)
-      URI(string_uri)
+      URI(File.join(@configuration.server_url, "realms", realm_id, path))
     end
   end
 end

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

@@ -8,36 +8,33 @@ 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)
+        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
 
-    def authentication_failed(message)
-      [401, {"Content-Type" => "application/json"}, [ { error: message }.to_json]]
+    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_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)
+    def authentication_failed(message)
+      # Rack 3 requires header names to be lowercase.
+      [401, { "content-type" => "application/json" }, [{ error: message }.to_json]]
     end
 
     def service

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

@@ -1,30 +1,49 @@
 module KeycloakApiRails
   class PublicKeyCachedResolver
+    FAILED_REFRESH_RETRY_DELAY_IN_SECONDS = 10
+
     attr_reader :cached_public_key_retrieved_at
 
-    def initialize(http_client, realm_id, public_key_cache_ttl)
+    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
     end
 
     def self.from_configuration(http_client, configuration)
-      PublicKeyCachedResolver.new(http_client, configuration.realm_id, configuration.public_key_cache_ttl)
+      new(http_client, configuration.realm_id, configuration.public_key_cache_ttl, configuration.logger)
     end
 
     def find_public_keys
-      if public_keys_are_outdated?
-        @cached_public_keys             = @resolver.find_public_keys
-        @cached_public_key_retrieved_at = Time.now
+      @mutex.synchronize do
+        refresh_public_keys if public_keys_are_outdated?
+        @cached_public_keys
       end
-      @cached_public_keys
     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}.")
+    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)
+      @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
 end

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

@@ -5,5 +5,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,43 @@
 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)
+      @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
-      else
-        raise TokenError.no_token(token)
+      raise TokenError.no_token(token) if token.nil? || token.empty?
+
+      public_keys = @key_resolver.find_public_keys
+      
+      if public_keys.nil?
+        raise MissingPublicKeysError, "No Keycloak public key is available to verify the token" 
       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)
+
+      decoded_token = decode(token, public_keys)
+      verify_claims!(token, decoded_token)
+      decoded_token
     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,14 +46,39 @@ 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
+
+    def verify_claims!(token, decoded_token)
+      raise TokenError.missing_claim(token, "exp") unless decoded_token.key?("exp")
+      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)
+    end
+
+    def normalize_skip_paths(skip_paths)
+      (skip_paths || {}).each_with_object({}) do |(method, paths), normalized|
+        normalized[method.to_s.downcase.to_sym] = Array(paths)
+      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&.to_s&.downcase&.to_sym]
+      !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 = method&.to_s&.downcase&.to_sym
       method_symbol == :options && !headers["HTTP_ACCESS_CONTROL_REQUEST_METHOD"].nil?
     end
 
@@ -56,5 +86,24 @@ module KeycloakApiRails
       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

@@ -38,19 +38,21 @@ module KeycloakApiRails
       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

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

@@ -1,30 +1,48 @@
-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
+module KeycloakApiRails
+  class TokenError < StandardError
+    attr_reader :token, :reason, :original_error
 
-  def self.verification_failed(token, original_error)
-    TokenError.new(token, :verification_failed, "Failed to verify JWT token", original_error)
-  end
+    def initialize(token, reason, message, original_error = nil)
+      super(message)
+      @token          = token
+      @reason         = reason
+      @original_error = original_error
+    end
 
-  def self.invalid_format(token, original_error)
-    TokenError.new(token, :invalid_format, "Wrong JWT Format", original_error)
-  end
+    def self.verification_failed(token, original_error)
+      new(token, :verification_failed, "Failed to verify JWT token", original_error)
+    end
 
-  def self.no_token(token)
-    TokenError.new(token, :no_token, "No JWT token provided", nil)
-  end
+    def self.invalid_format(token, original_error)
+      new(token, :invalid_format, "Wrong JWT Format", original_error)
+    end
 
-  def self.expired(token)
-    TokenError.new(token, :expired, "JWT token is expired", nil)
-  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.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,3 @@
 module KeycloakApiRails
-  VERSION = "1.1.2"
+  VERSION = "2.0.0"
 end

data/lib/keycloak-api-rails.rb

@@ -2,6 +2,7 @@ require "logger"
 require "json/jwt"
 require "uri"
 require "date"
+require "monitor"
 require "net/http"
 
 require_relative "keycloak-api-rails/authentication"
@@ -17,8 +18,13 @@ 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 { yield @configuration ||= KeycloakApiRails::Configuration.new }
   end
 
   def self.config
@@ -26,23 +32,25 @@ module KeycloakApiRails
   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
+      @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 +67,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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-api-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Lorent Lempereur
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -65,6 +65,34 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.9.11
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement