keycloak-api-rails 1.1.2 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74dec51fa027308c2cf5b57ca67b7316b21677bf1592022f76988f232bbde911
-  data.tar.gz: 4836a7951bbf1559ff5eec0dfeb004ff8bcd2955cee7e06ee9e8a553743ad99e
+  metadata.gz: 1e80ef54a212cf523766b3d1f0a4d836dd4f32c59322eb9b90a13e0e530bff08
+  data.tar.gz: c6757d2a355db048389b3c697557daea96e912eea4d2fbeea413b78bd888ce03
 SHA512:
-  metadata.gz: 48b3307f4dff316dfa063deddf0d106bbcc409856c20f0af5c441bdc3b1163e9cf93f0c3f7e53fd1a90fcb7946744c2b1b8863fd5a61a0c4012fe3d7df6b5aee
-  data.tar.gz: 81aca7224bcae644dd35f6fb715bdb447b0da549bc3da0bdd311a6bea06adfba468936aabcdaeb305a44839c6770a46644abfdf81f2f828246414880e9ab52dd
+  metadata.gz: 2e46089640ad0a1d9f14e08e383a5f651431f533d88e9444c809d8d4b55edc91460e668b1ff21e23e863583b4fd956056fb82b0ea9dc5e16ea34cccb268ad2cf
+  data.tar.gz: e4bfba00be03edd43b60394146bdad990b14eeb731d7e878bdf8944c00e92986278b4c11ca721fa99cd309c54289ee21e0b5199c4f357b4e614691e9d1b6b3b6

data/CHANGELOG.md

@@ -5,6 +5,93 @@ 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
+
+* `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.2"
 ```
 
 ## 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` |
-| `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` | 
+| `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"]` |
+| `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\/.+/] }`| 
+| `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` |
+| `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 (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` |
+| `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,47 @@ 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.
+
+## 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.
@@ -173,6 +223,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
 
@@ -181,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
@@ -266,14 +318,9 @@ 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.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
-* Avoid duplicate code in KeycloakApiRails::Middleware and `KeycloakApiRails::Authentication`

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module KeycloakApiRails
   module Authentication
     def self.included(base)
@@ -9,17 +11,18 @@ 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
       authentication_failed(e.message)
+    rescue KeycloakApiRails::HTTPError, KeycloakApiRails::MissingPublicKeysError => e
+      authentication_unavailable(e)
     end
 
     def authentication_failed(message)
@@ -27,15 +30,14 @@ 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_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,11 @@
+# frozen_string_literal: true
+
 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 +15,111 @@ 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, 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("'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(custom_attributes_errors)
+      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 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.is_a?(Regexp) }
+
+        "'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
+
+    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)
+      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
 
@@ -10,6 +12,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]
@@ -64,22 +78,33 @@ 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)
-      env[CURRENT_USER_ATTRIBUTES] = token.select { |key, value| attribute_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)
       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 +116,8 @@ module KeycloakApiRails
       else
         ""
       end
+    rescue URI::InvalidURIError, ArgumentError
+      nil
     end
 
     def self.create_url_with_token(uri, token)
@@ -102,7 +129,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,72 @@
+# frozen_string_literal: true
+
 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