keycloak-api-rails 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb67f66191b532371ed77f5677c4959a3d01cd8d4fa270dd984a119d796077b0
-  data.tar.gz: 64f29e21b50fb2d6f46d2a136c299aa9864c78aea977c9e4f7dc6a4927a28dff
+  metadata.gz: 1f53bfe86f8f72911bac95192b9a21fc0cf1ec01868e00f2cdd8edfcc57811e3
+  data.tar.gz: 2ad644c2561e191e9dd858055a9442df69fff0af02d078360164f1d41283f633
 SHA512:
-  metadata.gz: 2db5967b4c4b7e678763d015dd05567103cafb42bce12f0018c241df45400f8c4538309a59dd7526994bc14cf587aef3b7c51040d89ca2599c91c409b6acf8a5
-  data.tar.gz: 847fc92280c17a54d7f10976197b4ea0b37fea4217ee7ef9dd6d7089399b261831a07d3d56d07ffce2827aaf86c4332da680b3eaa044a3c35d0cb2347f123043
+  metadata.gz: da17e6a76b47460200ea397c58346dbdd43975f7aecec34e973b77ad15ebd12739d2c5d533064af24204d5be7bd4cc0f3c74b3df98e6d2623289a0d66f1398ad
+  data.tar.gz: 1f1f0ed249c2963fec160fdbdb6910a8387024f54d9956c35729fb5438037b541989046aee9dab2936dcc585d8f5e9ca6cd1b3247c20fb4dcea62ff7e2fae253

data/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+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

@@ -2,6 +2,7 @@
 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.

data/CHANGELOG.md

@@ -5,6 +5,11 @@ 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).
 
+## [1.1.1] - 2026-07-31
+
+* New test helpers, in `keycloak-api-rails/testing`: `KeycloakApiRails::Testing.stub_public_keys!` validates the tokens forged by `keycloak_token` and `keycloak_auth_headers`, so that controller and request tests can be authenticated without a Keycloak server, and without the boilerplate the README used to describe. This file is not loaded by `keycloak-api-rails` and has to be required explicitly
+* Publish the gem to RubyGems from Github Actions when a `v*` tag is pushed, using RubyGems' Trusted Publishing
+
 ## [1.1.0] - 2026-07-31
 
 * Dependencies: Upgrade test dependency `timecop` to `0.9.11`

data/README.md

@@ -18,7 +18,7 @@ the recommended path.
 ## Install
 
 ```ruby
-gem "keycloak-api-rails", "1.1.0"
+gem "keycloak-api-rails", "1.1.1"
 ```
 
 ## Token validation
@@ -191,36 +191,60 @@ end
 
 ## Writing integration tests
 
-If you want to write controller tests in your codebase and that Keycloak is configured for these controllers, here is how to mock it.
+If you want to write controller or request tests in your codebase and that Keycloak is configured for these controllers,
+this gem provides the helpers that forge valid tokens, so that no Keycloak server is required.
+These helpers are not loaded by `keycloak-api-rails`: they have to be required explicitly, so that nothing they define ends up in a production process.
 These lines are based on tests written using `rspec`.
 
-* First, create a private key. This key should be created once per test suite for performance matters.
 ```ruby
-config.before(:suite) do
-  $private_key = OpenSSL::PKey::RSA.generate(1024)
+# spec/rails_helper.rb
+require "keycloak-api-rails/testing"
+
+RSpec.configure do |config|
+  config.include KeycloakApiRails::Testing::Helpers
+  config.before(:suite) { KeycloakApiRails::Testing.stub_public_keys! }
 end
 ```
-* Then, in a `shared_context`, configure a lazy token based on your main user. (here, we assume you have a `user` variable with a `keycloak_id` property)
+
+`stub_public_keys!` makes the library validate the tokens forged by these helpers, instead of fetching public keys from a Keycloak server.
+`server_url` and `realm_id` therefore do not have to be configured in the test environment. Requests can then be authenticated with:
+
 ```ruby
-let(:jwt) do
-  claims = {
-    iat: Time.zone.now.to_i,
-    exp: (Time.zone.now + 1.day).to_i,
-    sub: user.keycloak_id,
-  }
-  token = JSON::JWT.new(claims)
-  token.kid = "default"
-  token.sign($private_key, :RS256).to_s
+it "returns the current user" do
+  get "/me", headers: keycloak_auth_headers(sub: user.keycloak_id)
+
+  expect(response).to have_http_status(:ok)
 end
 ```
-* Finally, in the same `shared_context`, stub `KeycloakApiRails.public_key_resolver` to use a valid public key that is able to validate `jwt`:
+
+`keycloak_auth_headers` returns an `Authorization` header, and `keycloak_token` returns the token alone.
+Both accept the same optional parameters, one for each claim this library reads:
+
+| Parameter | Claim | Default |
+| --- | --- | --- |
+| `sub` | `sub` | a random UUID |
+| `email` | `email` | none |
+| `locale` | `locale` | none |
+| `authorized_party` | `azp` | none |
+| `roles` | `realm_access.roles` | none |
+| `resource_roles` | `resource_access` | none |
+| `issued_at` | `iat` | now |
+| `expires_at` | `exp` | one hour after `issued_at` |
+| `claims` | any other claim | none |
+
+For instance, to authenticate a request as a user having the realm role `admin`, the role `reader` on the client `a-client`,
+and a `tenant_id` attribute declared in `config.custom_attributes`:
+
 ```ruby
-before(:each) do
-  public_key_resolver = KeycloakApiRails.public_key_resolver
-  allow(public_key_resolver).to receive(:find_public_keys) { JSON::JWK::Set.new(JSON::JWK.new($private_key, kid: "default")) }
-end
+headers = keycloak_auth_headers(sub:            user.keycloak_id,
+                                roles:          ["admin"],
+                                resource_roles: { "a-client" => ["reader"] },
+                                claims:         { "tenant_id" => tenant.id })
 ```
 
+An expired token is forged by passing an `expires_at` in the past, which is how a `401` can be tested.
+Assigning `KeycloakApiRails.public_key_resolver = nil` restores the regular resolver.
+
 ## How to execute library tests
 
 From the `keycloak-rails-api` directory:
@@ -230,6 +254,25 @@ From the `keycloak-rails-api` directory:
   $ docker run -v `pwd`:/usr/src/app/ keycloak-rails-api:test bundle exec rspec spec
 ```
 
+## How to release a new version
+
+Releases are published to [RubyGems](https://rubygems.org/gems/keycloak-api-rails) by GitHub Actions
+(`.github/workflows/release.yml`), through [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/):
+no API key is stored in this repository, the workflow exchanges a short-lived GitHub OIDC token for a
+scoped RubyGems credential.
+
+1. Update `KeycloakApiRails::VERSION` in `lib/keycloak-api-rails/version.rb` and the `CHANGELOG.md`
+2. Commit and push these changes to `main`
+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
+```
+
+The workflow then checks that the tag matches `KeycloakApiRails::VERSION`, runs the tests, builds the gem
+and pushes it. It only publishes tags starting with `v`.
+
 ## Next developments
 
 * Manage multiple realms

data/Rakefile

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

data/keycloak-api-rails.gemspec

@@ -22,6 +22,8 @@ Gem::Specification.new do |spec|
 
   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 "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"

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

@@ -0,0 +1,118 @@
+# Test helpers for the applications that authenticate their requests with this library.
+#
+# This file is *not* loaded by "keycloak-api-rails": it has to be required explicitly, so that
+# nothing it defines can end up in a production process.
+#
+#   # spec/rails_helper.rb
+#   require "keycloak-api-rails/testing"
+#
+#   RSpec.configure do |config|
+#     config.include KeycloakApiRails::Testing::Helpers
+#     config.before(:suite) { KeycloakApiRails::Testing.stub_public_keys! }
+#   end
+#
+# Requests can then be authenticated without a running Keycloak, and without configuring
+# 'server_url' or 'realm_id':
+#
+#   get "/me", headers: keycloak_auth_headers(sub: user.keycloak_id, roles: ["admin"])
+
+require_relative "../keycloak-api-rails"
+require "securerandom"
+
+module KeycloakApiRails
+  module Testing
+
+    KEY_SIZE                    = 2048
+    KEY_ID                      = "keycloak-api-rails-testing"
+    ALGORITHM                   = :RS256
+    DEFAULT_VALIDITY_IN_SECONDS = 3600
+
+    # Returns the public keys forged by this module, instead of fetching them from a Keycloak server.
+    class PublicKeyResolver
+      def initialize(public_keys)
+        @public_keys = public_keys
+      end
+
+      def find_public_keys
+        @public_keys
+      end
+    end
+
+    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)
+      end
+
+      def signing_key
+        @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))
+      end
+
+      # Makes the library validate the tokens forged by this module. Assigning
+      # 'KeycloakApiRails.public_key_resolver = nil' restores the regular resolver.
+      def stub_public_keys!
+        KeycloakApiRails.public_key_resolver = PublicKeyResolver.new(public_keys)
+      end
+
+      # Forges a signed token, similar to the ones emitted by Keycloak. Every claim this library
+      # reads has a dedicated parameter; any other claim can be passed through 'claims', which is
+      # also how the attributes declared in 'config.custom_attributes' are set.
+      def token_for(sub: SecureRandom.uuid,
+                    email: nil,
+                    locale: nil,
+                    authorized_party: nil,
+                    roles: [],
+                    resource_roles: {},
+                    issued_at: Time.now,
+                    expires_at: nil,
+                    claims: {})
+        payload = {
+          "sub"    => sub,
+          "email"  => email,
+          "locale" => locale,
+          "azp"    => authorized_party,
+          "iat"    => issued_at.to_i,
+          "exp"    => (expires_at || (issued_at.to_i + DEFAULT_VALIDITY_IN_SECONDS)).to_i
+        }.reject { |_, value| value.nil? }
+
+        payload["realm_access"]    = { "roles" => roles.map(&:to_s) } unless roles.nil? || roles.empty?
+        payload["resource_access"] = build_resource_access(resource_roles) unless resource_roles.nil? || resource_roles.empty?
+
+        claims.each { |name, value| payload[name.to_s] = value }
+
+        JSON::JWT.new(payload).sign(signing_key, ALGORITHM).to_s
+      end
+
+      # The 'Authorization' header a client would send, e.g. { "Authorization" => "Bearer eyJ0..." }.
+      # It accepts the same parameters as '.token_for'.
+      def auth_headers_for(**options)
+        { "Authorization" => "Bearer #{token_for(**options)}" }
+      end
+
+      private
+
+      def build_resource_access(resource_roles)
+        resource_roles.inject({}) do |resource_access, (name, roles)|
+          resource_access[name.to_s] = { "roles" => Array(roles).map(&:to_s) }
+          resource_access
+        end
+      end
+    end
+
+    # Meant to be included in a test suite, e.g. 'config.include KeycloakApiRails::Testing::Helpers'.
+    module Helpers
+      def keycloak_token(**options)
+        KeycloakApiRails::Testing.token_for(**options)
+      end
+
+      def keycloak_auth_headers(**options)
+        KeycloakApiRails::Testing.auth_headers_for(**options)
+      end
+    end
+  end
+end

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

@@ -1,3 +1,3 @@
 module KeycloakApiRails
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

data/lib/keycloak-api-rails.rb

@@ -33,6 +33,14 @@ module KeycloakApiRails
     @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
+  end
+
   def self.service
     @service ||= KeycloakApiRails::Service.new(public_key_resolver)
   end

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

@@ -205,6 +205,12 @@ RSpec.describe KeycloakApiRails::Service do
         @result = service2.need_middleware_authentication?(method, path, headers)
       end
 
+      # The configuration is global: leaving 'opt_in' enabled would disable the authentication
+      # of every example running afterwards.
+      after do
+        KeycloakApiRails.config.opt_in = false
+      end
+
       it "should return false" do
         expect(@result).to be false
       end

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

@@ -0,0 +1,102 @@
+require_relative "../../lib/keycloak-api-rails/testing"
+
+RSpec.describe KeycloakApiRails::Testing do
+  include KeycloakApiRails::Testing::Helpers
+
+  # The tokens are validated by the real middleware and the real service, so that these examples
+  # fail if what this module forges stops being what the library expects.
+  let(:authenticated_env) { {} }
+  let(:app) do
+    downstream = lambda do |env|
+      authenticated_env.replace(env)
+      [200, {}, ["OK"]]
+    end
+    KeycloakApiRails::Middleware.new(downstream)
+  end
+
+  def get(headers)
+    app.call({
+      "REQUEST_METHOD"    => "GET",
+      "PATH_INFO"         => "/me",
+      "REQUEST_URI"       => "http://example.org/me",
+      "HTTP_AUTHORIZATION" => headers["Authorization"]
+    })
+  end
+
+  before(:each) do
+    # The middleware only authenticates a request when the configuration tells it to, and the
+    # configuration is global: these examples cannot rely on what the other ones leave behind.
+    KeycloakApiRails.config.opt_in    = false
+    KeycloakApiRails.config.skip_paths = {}
+    KeycloakApiRails::Testing.stub_public_keys!
+  end
+
+  after(:each) do
+    KeycloakApiRails.public_key_resolver = nil
+  end
+
+  describe ".stub_public_keys!" do
+    it "should validate the tokens forged by this module" do
+      status, _headers, _body = get(keycloak_auth_headers)
+
+      expect(status).to eq(200)
+    end
+
+    it "should not require a Keycloak server to be configured" do
+      expect(KeycloakApiRails.config.server_url).to be_nil
+      expect(KeycloakApiRails.config.realm_id).to be_nil
+
+      status, _headers, _body = get(keycloak_auth_headers)
+
+      expect(status).to eq(200)
+    end
+  end
+
+  describe ".token_for" do
+    it "should authenticate the given user" do
+      get(keycloak_auth_headers(sub: "a-keycloak-id"))
+
+      expect(KeycloakApiRails::Helper.current_user_id(authenticated_env)).to eq("a-keycloak-id")
+    end
+
+    it "should generate a different user for each token" do
+      first_token  = JSON::JWT.decode(keycloak_token, KeycloakApiRails::Testing.public_keys)
+      second_token = JSON::JWT.decode(keycloak_token, KeycloakApiRails::Testing.public_keys)
+
+      expect(first_token["sub"]).not_to eq(second_token["sub"])
+    end
+
+    it "should expose every claim read by the library" do
+      get(keycloak_auth_headers(sub:              "a-keycloak-id",
+                                email:            "an-email@keycloak.io",
+                                locale:           "fr",
+                                authorized_party: "a-client",
+                                roles:            ["admin", "user"],
+                                resource_roles:   { "a-client" => ["reader"] }))
+
+      expect(KeycloakApiRails::Helper.current_user_id(authenticated_env)).to eq("a-keycloak-id")
+      expect(KeycloakApiRails::Helper.current_user_email(authenticated_env)).to eq("an-email@keycloak.io")
+      expect(KeycloakApiRails::Helper.current_user_locale(authenticated_env)).to eq("fr")
+      expect(KeycloakApiRails::Helper.current_authorized_party(authenticated_env)).to eq("a-client")
+      expect(KeycloakApiRails::Helper.current_user_roles(authenticated_env)).to eq(["admin", "user"])
+      expect(KeycloakApiRails::Helper.current_resource_roles(authenticated_env)).to eq({ "a-client" => ["reader"] })
+    end
+
+    it "should expose the claims declared as custom attributes" do
+      KeycloakApiRails.config.custom_attributes = ["tenant_id"]
+
+      get(keycloak_auth_headers(claims: { "tenant_id" => "a-tenant" }))
+
+      expect(KeycloakApiRails::Helper.current_user_custom_attributes(authenticated_env)).to eq({ "tenant_id" => "a-tenant" })
+    ensure
+      KeycloakApiRails.config.custom_attributes = []
+    end
+
+    it "should forge a token that is expired when 'expires_at' is in the past" do
+      status, _headers, body = get(keycloak_auth_headers(issued_at: Time.now - 7200, expires_at: Time.now - 3600))
+
+      expect(status).to eq(401)
+      expect(body.first).to include("JWT token is expired")
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-api-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Lorent Lempereur
@@ -65,6 +65,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.9.11
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -87,6 +101,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rspec"
 - CHANGELOG.md
@@ -94,6 +109,7 @@ files:
 - Gemfile
 - MIT-LICENSE
 - README.md
+- Rakefile
 - keycloak-api-rails.gemspec
 - lib/keycloak-api-rails.rb
 - lib/keycloak-api-rails/authentication.rb
@@ -105,6 +121,7 @@ files:
 - lib/keycloak-api-rails/public_key_resolver.rb
 - lib/keycloak-api-rails/railtie.rb
 - lib/keycloak-api-rails/service.rb
+- 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
@@ -113,6 +130,7 @@ files:
 - 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
@@ -136,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails middleware that validates Authorization token emitted by Keycloak
 test_files: []