keycloak-api-rails 2.0.3 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75cb985d142693a50337445bdde2608ee636c3ce77327e577a88f1d3ad6f12d7
-  data.tar.gz: a9220359016e6c96f594d2e43485bb2e5c2821da9d2055c6c622eef26fcdf33f
+  metadata.gz: e074e3c78c789139c8eeaf6a127dceaf0c7ff7235c1134f3fa0ea3c4149b277a
+  data.tar.gz: 6b4a5b9faaa16ab883a25c03e5eb31a0c8740f80b784812d6f47eb7aae117eb3
 SHA512:
-  metadata.gz: fab532886c13b4e2b950ff31b591d9670b0d8a343e835afa8922b35cd742142f63a6943685332d9ad5baf1146344dd6ff452209793f8dc7864c5a3322a520fad
-  data.tar.gz: 0c8110fc856d3e74e49fb675749fcdac113808d140a15c29c01838abcd760ef10ff78527aec128e5c7eaa2c8d7d879ef1ebe111972fd1d0e8671ad188c2f638c
+  metadata.gz: 9472f08064d6a3e3ba64b781f089d2a42861b26323f9eba3a752ec63d41e54f32288b82ed0fa1b12e46418e9c1771351c7be8676476303162e88a28d676655bd
+  data.tar.gz: 0f106f193ceaa023611b9128910b5f944ebfe213c7b7fc1237f7a2e49c55c9b76564ac84ef080e3a4c36f48bcb463da434756d00af5f370cc07a5e8842c5c0f6

data/CHANGELOG.md

@@ -5,7 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.0.4] - 2026-08-03
+
+### Added
+
+* New `issuer_url` option: the `iss` claim is checked against it instead of `server_url` when set, for setups where the API reaches Keycloak through a different address than the one Keycloak advertises to its clients (e.g. an internal Docker hostname vs. a public one).
+
+## [2.0.3] - 2026-08-03
 
 ### Security
 

data/README.md

@@ -18,7 +18,7 @@ the recommended path.
 ## Install
 
 ```ruby
-gem "keycloak-api-rails", "2.0.3"
+gem "keycloak-api-rails", "2.0.4"
 
 ## Token validation
 
@@ -60,6 +60,7 @@ 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, scheme included. Without one, the url cannot be parsed and no public key is ever downloaded | `https://keycloak.example.org` or `http://auth:8080` |
+| `issuer_url` | `server_url`| String | Optional | The base url expected in a token's `iss` claim, when it differs from `server_url`. Needed when the API reaches Keycloak through a different address than the one Keycloak advertises to its clients, e.g. an internal Docker hostname vs. a public one | `https://keycloak.example.org` |
 | `realm_id` | `nil`| String, Array or Proc | Required | Realm's name(s) (not id, actually). A single String, an Array of Strings for multiple tenants, or a Proc receiving the realm named by the token and answering whether it is allowed | `"master"`, `["tenant1", "tenant2"]` or `->(realm) { Tenant.exists?(name: realm) }` |
 | `logger` | `Logger.new(STDOUT)`| Logger | Optional | The logger used by `keycloak-api-rails` | `Rails.logger` | 
 | `skip_paths` | `{}`| Hash of methods and paths regexp | Optional | Paths whose token must not be validated, matched against the URL-decoded path of the request. Each path must be a `Regexp`, anchored with `\A` and `\z`: a String is refused when the application boots, and `^` and `$` are warned about, for the reasons given below | `{ get: [/\A\/health\/.+/] }`| 
@@ -136,14 +137,26 @@ Keycloak only adds an API to the `aud` claim of a token once that API is declare
 `config.verify_not_before = true` additionally rejects a token whose `nbf` claim is in the future.
 It is disabled by default because a clock skew between Keycloak and the API rejects valid tokens.
 
-The `iss` claim is checked against `server_url` only when one is configured. A test environment replacing the public key resolver, as `keycloak-api-rails/testing` does, accepts any issuer.
+The `iss` claim is checked against `issuer_url`, or `server_url` when `issuer_url` is not configured, only when one of the two is set. A test environment replacing the public key resolver, as `keycloak-api-rails/testing` does, accepts any issuer.
+
+## When Keycloak is reached through a different address than its own
+
+`server_url` is used both to download public keys and, absent `issuer_url`, to check the `iss` claim. Those are two different needs: the former must be an address the API can reach, the latter must match what Keycloak put in the token, which is whatever address its own clients used. Behind a reverse proxy, or from inside Docker, these are often not the same:
+
+```ruby
+KeycloakApiRails.configure do |config|
+  config.server_url = "http://keycloak:8080"           # reachable from the API container
+  config.issuer_url = "https://keycloak.example.org"    # what Keycloak's own hostname config puts in `iss`
+  config.realm_id   = ENV["KEYCLOAK_REALM_ID"]
+end
+```
 
 ## Multi-tenancy (Multiple Realms)
 
 The library natively supports multi-tenancy by validating tokens issued by multiple Keycloak realms. 
 Instead of a static string, you can configure `realm_id` with an Array or a Proc. The library will dynamically extract the realm from the token's `iss` claim, check if it is permitted, and fetch the appropriate public keys for that specific realm.
 
-Those realms all live under the same `server_url`: a token whose `iss` names another server is rejected, however allowed the realm it names.
+Those realms all live under the same `server_url` (or `issuer_url`, when configured): a token whose `iss` names another server is rejected, however allowed the realm it names.
 Declaring `expected_audience` matters all the more here — without it, a token issued for any client of any allowed realm opens the API.
 
 Using an Array of allowed realms:
@@ -344,8 +357,8 @@ scoped RubyGems credential.
 3. Tag the commit and push the tag:
 
 ```
-  $ git tag -a v2.0.3 -m "Version 2.0.3"
-  $ git push origin v2.0.3
+  $ git tag -a v2.0.4 -m "Version 2.0.4"
+  $ git push origin v2.0.4
 ```
 
 The workflow then checks that the tag matches `KeycloakApiRails::VERSION`, runs the tests, builds the gem

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

@@ -7,6 +7,7 @@ module KeycloakApiRails
     LOGGER_METHODS = [:debug, :info, :warn, :error].freeze
 
     attr_accessor :server_url
+    attr_accessor :issuer_url
     attr_accessor :realm_id
     attr_accessor :skip_paths
     attr_accessor :opt_in
@@ -27,6 +28,7 @@ module KeycloakApiRails
       errors = []
 
       errors.push("'server_url' must be a String or nil, got #{server_url.inspect}") unless server_url.nil? || server_url.is_a?(String)
+      errors.push("'issuer_url' must be a String or nil, got #{issuer_url.inspect}") unless issuer_url.nil? || issuer_url.is_a?(String)
       errors.push("'realm_id' must be a String, an Array of Strings, a Proc, or nil, got #{realm_id.inspect}") unless valid_realm_id?(realm_id)
       errors.push("'logger' must respond to #{LOGGER_METHODS.join(', ')}") unless LOGGER_METHODS.all? { |method| logger.respond_to?(method) }
       errors.push("'opt_in' must be true or false, got #{opt_in.inspect}") unless boolean?(opt_in)

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

@@ -116,8 +116,9 @@ module KeycloakApiRails
       raise TokenError.invalid_audience(token)     unless audience_valid?(decoded_token)
       raise TokenError.invalid_token_type(token)   unless token_type_valid?(decoded_token)
 
-      if KeycloakApiRails.config.server_url
-        expected_iss = File.join(KeycloakApiRails.config.server_url.to_s, "realms", realm_id.to_s)
+      issuer_url = KeycloakApiRails.config.issuer_url || KeycloakApiRails.config.server_url
+      if issuer_url
+        expected_iss = File.join(issuer_url.to_s, "realms", realm_id.to_s)
         raise TokenError.invalid_realm(token) unless decoded_token["iss"] == expected_iss
       end
     end

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

@@ -90,7 +90,8 @@ module KeycloakApiRails
         unless claims.key?(:iss) || claims.key?("iss")
           config_realm_id = KeycloakApiRails.config.realm_id
           realm_id = config_realm_id.is_a?(String) ? config_realm_id : "master"
-          payload["iss"] = File.join(KeycloakApiRails.config.server_url.to_s, "realms", realm_id)
+          issuer_url = KeycloakApiRails.config.issuer_url || KeycloakApiRails.config.server_url
+          payload["iss"] = File.join(issuer_url.to_s, "realms", realm_id)
         end
 
         claims.each { |name, value| payload[name.to_s] = value }

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

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

data/lib/keycloak-api-rails.rb

@@ -78,6 +78,7 @@ module KeycloakApiRails
   def self.load_configuration
     configure do |config|
       config.server_url                             = nil
+      config.issuer_url                             = nil
       config.realm_id                               = nil
       config.logger                                 = ::Logger.new(STDOUT)
       config.skip_paths                             = {}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-api-rails
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.0.4
 platform: ruby
 authors:
 - Lorent Lempereur