keycloak-api-rails 1.1.1 → 2.0.0

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.1"
+  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.1
+  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
@@ -93,23 +121,19 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 11.1.3
-description: Rails middleware that validates Authorization token emitted by Keycloak
+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
+  attributes of the token to the controllers, and lets some routes opt out of authentication.
 email:
 - lorent.lempereur.dev@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/ci.yml"
-- ".github/workflows/release.yml"
-- ".gitignore"
-- ".rspec"
 - CHANGELOG.md
-- Dockerfile
-- Gemfile
 - MIT-LICENSE
 - README.md
-- Rakefile
 - keycloak-api-rails.gemspec
 - lib/keycloak-api-rails.rb
 - lib/keycloak-api-rails/authentication.rb
@@ -124,22 +148,14 @@ files:
 - lib/keycloak-api-rails/testing.rb
 - lib/keycloak-api-rails/token_error.rb
 - lib/keycloak-api-rails/version.rb
-- spec/keycloak-api-rails/activesupport_free_spec.rb
-- spec/keycloak-api-rails/authentication_spec.rb
-- spec/keycloak-api-rails/configuration_spec.rb
-- spec/keycloak-api-rails/helper_spec.rb
-- spec/keycloak-api-rails/public_key_cached_resolver_spec.rb
-- spec/keycloak-api-rails/service_spec.rb
-- spec/keycloak-api-rails/testing_spec.rb
-- spec/spec_helper.rb
-- spec/support/activesupport_free_probe.rb
-- spec/support/public_key_cached_resolver_stub.rb
-- spec/support/public_key_resolver_stub.rb
-- spec/support/rails_helper.rb
 homepage: https://github.com/looorent/keycloak-api-rails
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/looorent/keycloak-api-rails
+  changelog_uri: https://github.com/looorent/keycloak-api-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/looorent/keycloak-api-rails/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib

data/.github/workflows/ci.yml

@@ -1,35 +0,0 @@
-name: Ruby
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    name: Ruby ${{ matrix.ruby-version }}
-    # Pinned rather than 'ubuntu-latest': ruby/setup-ruby has no prebuilt Rubies for
-    # ubuntu-26.04 yet, so the oldest versions of the matrix would break once the
-    # 'latest' alias moves on.
-    runs-on: ubuntu-24.04
-
-    strategy:
-      fail-fast: false
-      matrix:
-        # Each version resolves the newest dependencies it supports: Rails 7.1 on Ruby 2.7
-        # and 3.0, Rails 7.2 on Ruby 3.1, Rails 8.1 on Ruby 3.2 and above.
-        ruby-version: ['2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0']
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-    - name: Run tests
-      run: bundle exec rspec

data/.github/workflows/release.yml

@@ -1,52 +0,0 @@
-name: Release
-
-# Publishing is triggered by pushing a version tag, e.g.:
-#   git tag -a v1.2.0 -m "Version 1.2.0" && git push origin v1.2.0
-#
-# No RubyGems API key is stored in this repository: the gem is pushed through
-# RubyGems' Trusted Publishing, which exchanges a short-lived GitHub OIDC token
-# for a scoped RubyGems credential. This requires a trusted publisher declared on
-# https://rubygems.org/gems/keycloak-api-rails pointing to this repository, this
-# workflow file name and the 'release' environment.
-on:
-  push:
-    tags: [ "v*" ]
-
-permissions:
-  contents: read
-
-jobs:
-  release:
-    name: Push gem to RubyGems.org
-    # Pinned rather than 'ubuntu-latest', for the same reason as in ci.yml.
-    runs-on: ubuntu-24.04
-
-    environment: release
-
-    permissions:
-      contents: write # 'rake release' pushes the version tag when it does not exist yet
-      id-token: write # mandatory to request the OIDC token used by trusted publishing
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: '3.4'
-        bundler-cache: true
-
-    - name: Check that the tag matches KeycloakApiRails::VERSION
-      run: |
-        tag="${GITHUB_REF_NAME#v}"
-        version="$(ruby -Ilib -r keycloak-api-rails/version -e 'print KeycloakApiRails::VERSION')"
-        if [ "$tag" != "$version" ]; then
-          echo "::error::Tag '${GITHUB_REF_NAME}' does not match KeycloakApiRails::VERSION '${version}'"
-          exit 1
-        fi
-
-    - name: Run tests
-      run: bundle exec rspec
-
-    # Builds the gem, pushes it to RubyGems.org and waits for it to be available.
-    - uses: rubygems/release-gem@v1

data/.gitignore

@@ -1,9 +0,0 @@
-.bundle/
-log/*.log
-.byebug_history
-*.gem
-pkg/
-# This gem supports several Ruby versions, each of them resolving a different set of
-# dependencies (Ruby 2.7 caps Rails to 7.1, Ruby 3.1 to 7.2, Ruby 3.2+ resolves Rails 8.1).
-# A single committed lockfile cannot satisfy all of them.
-Gemfile.lock

data/.rspec

@@ -1,2 +0,0 @@
---color
---require spec_helper

data/Dockerfile

@@ -1,13 +0,0 @@
-FROM ruby:3.4.10-slim-bookworm
-
-RUN apt-get update -qq && apt-get install -y build-essential git ruby-dev && apt-get clean && \
-  mkdir -p /usr/src/app/lib/keycloak-api-rails
-
-WORKDIR /usr/src/app
-
-COPY Gemfile /usr/src/app/
-COPY keycloak-api-rails.gemspec /usr/src/app/
-COPY lib/keycloak-api-rails/version.rb /usr/src/app/lib/keycloak-api-rails/
-RUN bundle install
-COPY . /usr/src/app
-RUN bundle install

data/Gemfile

@@ -1,3 +0,0 @@
-source 'https://rubygems.org'
-
-gemspec

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec

data/spec/keycloak-api-rails/activesupport_free_spec.rb

@@ -1,18 +0,0 @@
-require "rbconfig"
-
-RSpec.describe "The library without ActiveSupport" do
-
-  let(:probe) { File.expand_path("../../support/activesupport_free_probe.rb", __FILE__) }
-
-  # RUBYOPT is cleared so that nothing set up by bundler is preloaded in the probe process.
-  def run_probe
-    output = IO.popen({ "RUBYOPT" => nil }, [RbConfig.ruby, probe], err: [:child, :out], &:read)
-    [$?.exitstatus, output]
-  end
-
-  it "loads and behaves the same way when ActiveSupport is not available" do
-    status, output = run_probe
-
-    expect(status).to eq(0), "The library relies on ActiveSupport:\n#{output}"
-  end
-end