verikloak 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be8192b1562ca02e7da55d8451e5588907707b3677c7343c14fc9448c8dc8cdc
-  data.tar.gz: f2eed617dbcae935e8691c72230361da981046414b9c64557d73e5a3a683df42
+  metadata.gz: f694670478e8bbeff2369e0898b96a2d675e052bc19c4ac8437bfb3ff209dc52
+  data.tar.gz: 8c189a0ae636ee82ab5e0589b047327c6bd5c8360d4a40f3fcbb6ebc1491743b
 SHA512:
-  metadata.gz: a5b3aef46de49a76e52a19edf022a079a343df6ec583da65f193708a0dbd950874d2a2f0e1538f3748f7ce77c78da1ff7386ee177628f8054937f2d08ddb4e22
-  data.tar.gz: 5160853c31143b7581b512022047ab4990d39bda1644d7d57622ca22cfed15506669a10a77c809af0e220cbddd4e7b347ff58bd96037d5d6ec6605894a3910b5
+  metadata.gz: 456fb93fd6afd7376d4daedc1fe17c708d0b0c7055e5e215874418b84de69fbee048f70fc421560ae3e0296d264f5d4f0be1028382f28798531c292be7bc5ba1
+  data.tar.gz: 2f7f2107e34117cbc644b6b1c862da9521b9f1bda47a862ffb6747ad8a1bd851a3217ebc41113552684e1b67887074dfe845a14e6a0ae50cc7aaa6c4318a9665

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.0.2] - 2026-05-09
+
+### Fixed
+- **`iat` claim now honors `leeway`** (`TokenDecoder`): On ruby-jwt 3.x the built-in `Claims::IssuedAt` validator ignores the `leeway` option and raises `JWT::InvalidIatError` whenever `iat` is even a fraction of a second in the future. In typical OIDC deployments the IdP (e.g. Keycloak) and the Resource Server run on different hosts/containers, so `iat` is routinely a few hundred milliseconds to a few seconds ahead of the Resource Server's clock and the previously-effective leeway of `0` for `iat` produced spurious 401s. `TokenDecoder` now disables ruby-jwt's built-in `iat` check and performs its own `iat` validation that applies the configured `leeway` consistently with `exp` and `nbf`. Behaviour for tokens with `iat` further in the future than `leeway` is unchanged (still rejected with `invalid_token`). Pass `options: { verify_iat: false }` to skip the check entirely.
+- **`iat` validation now handles symbol-keyed payloads**: `verify_iat_with_leeway!` looks up both `'iat'` and `:iat`, so callers who request symbol-keyed payloads from `JWT.decode` still get the leeway-aware `iat` check applied.
+
+### Security
+- **Bumped `rack` to `>= 3.2.6` and `json` to `>= 2.19.5`** in `Gemfile.lock` to clear known advisories surfaced by `bundler-audit` (rack request-smuggling and json format-string injection).
+
+---
+
+## [1.0.1] - 2026-02-15
+
+### Fixed
+- **SSRF protection bypass for development mode**: `allow_http: true` now also skips private IP validation in both `JwksCache` (initial `jwks_uri` resolution) and `Discovery` (redirect target resolution). Previously, even with `allow_http: true`, connections to Keycloak on private/loopback IPs (e.g. `127.0.0.1`, `10.x.x.x`, `192.168.x.x`) were blocked by SSRF protection, making local development impossible.
+- **Inconsistent SSRF behaviour**: `Discovery#fetch!` did not validate the initial discovery URL against private IPs (only redirect targets), while `JwksCache` unconditionally blocked private IPs at initialisation. Both now consistently skip private IP checks when `allow_http: true`.
+
+---
+
 ## [1.0.0] - 2026-02-15
 
 ### Security

data/README.md

@@ -18,7 +18,7 @@ Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that
 - Rails/Rack middleware support
 - Faraday-based customizable HTTP layer
 - HTTPS enforcement for Discovery and JWKs endpoints (with `allow_http:` escape hatch for development)
-- SSRF protection — discovery redirect targets **and** `jwks_uri` values validated against private IP ranges (including IPv4-mapped IPv6 normalisation)
+- SSRF protection — discovery redirect targets **and** `jwks_uri` values validated against private IP ranges (including IPv4-mapped IPv6 normalisation); automatically bypassed with `allow_http: true` for local development
 - HTTPS redirect enforcement — redirect targets are scheme-checked to prevent HTTPS→HTTP downgrade
 - JWT size limit (8 KB) to mitigate denial-of-service via oversized tokens
 - Header injection prevention in `WWW-Authenticate` responses
@@ -225,7 +225,7 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `discovery_redirect_error` | 503 Service Unavailable   | Discovery redirect error: missing/invalid Location header, redirect target resolves to a private IP (SSRF protection), redirect uses non-HTTPS scheme, or unsupported scheme |
 | `insecure_discovery_url`   | 503 Service Unavailable   | Discovery URL uses `http://` and `allow_http: true` is not set                               |
 | `insecure_jwks_uri`        | 503 Service Unavailable   | JWKs URI uses `http://` and `allow_http: true` is not set                                    |
-| `jwks_ssrf_blocked`        | 503 Service Unavailable   | JWKs URI hostname resolves to a private/loopback IP address (SSRF protection)                |
+| `jwks_ssrf_blocked`        | 503 Service Unavailable   | JWKs URI hostname resolves to a private/loopback IP address (SSRF protection; bypassed when `allow_http: true`) |
 | `internal_server_error`    | 500 Internal Server Error | Unexpected internal error (catch-all)                                                        |
 
 > **Note:** The `decode_with_public_key` method ensures consistent error codes for all JWT verification failures.  
@@ -250,7 +250,7 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `user_env_key`  | No       | Rack env key for decoded claims. Defaults to `verikloak.user`. |
 | `realm`         | No       | Value used in the `WWW-Authenticate` header. Defaults to `verikloak`. |
 | `logger`        | No       | Logger for unexpected internal failures (responds to `error`, optionally `debug`). |
-| `allow_http`    | No       | When `false` (default), `Discovery` and `JwksCache` reject plain `http://` URLs. Set `true` **only** for local development against a non-TLS Keycloak instance. |
+| `allow_http`    | No       | When `false` (default), `Discovery` and `JwksCache` reject plain `http://` URLs and block private/loopback IPs (SSRF protection). Set `true` **only** for local development against a non-TLS Keycloak instance — this also bypasses private IP checks so that Keycloak on `localhost` or LAN addresses works out of the box. |
 
 #### Option: `skip_paths`
 
@@ -336,8 +336,21 @@ config.middleware.use Verikloak::Middleware,
   }
 ```
 
-- `leeway:` sets the default skew tolerance in seconds.
-- `token_verify_options:` is passed directly to TokenDecoder (and ultimately to `JWT.decode`).
+- `leeway:` sets the default skew tolerance in seconds. It is applied to
+  `exp`, `nbf`, and `iat`. Verikloak applies leeway to `iat` itself
+  because ruby-jwt 3.x's built-in `iat` validator ignores the `leeway`
+  option; pass `token_verify_options: { verify_iat: false }` to skip the
+  `iat` check entirely.
+- `token_verify_options:` is forwarded to `TokenDecoder` (and ultimately
+  to `JWT.decode`), with the following keys handled by Verikloak rather
+  than passed through verbatim:
+  - `:leeway` — Verikloak forwards it to `JWT.decode` so it applies to
+    `exp`/`nbf`, and also uses it for its own `iat` check.
+  - `:verify_iat` — ruby-jwt's built-in `iat` validator is always
+    disabled (it ignores `:leeway` on ruby-jwt 3.x). Setting
+    `verify_iat: false` instead skips Verikloak's own `iat` check;
+    setting `verify_iat: true` (the default) keeps it enabled.
+  All other keys are forwarded to `JWT.decode` as-is.
 - If both are set, `token_verify_options[:leeway]` takes precedence.
 
 ## Performance & Caching

data/lib/verikloak/discovery.rb

@@ -267,10 +267,13 @@ module Verikloak
 
     # Validates that the redirect target does not resolve to a private/internal IP.
     # IPv4-mapped IPv6 addresses are normalised before comparison.
+    # Skipped when `@allow_http` is true (development mode).
     # @api private
     # @param uri [URI] Parsed redirect target
     # @raise [DiscoveryError]
     def validate_redirect_not_private!(uri)
+      return if @allow_http
+
       host = uri.host
       return unless host
 

data/lib/verikloak/jwks_cache.rb

@@ -61,7 +61,7 @@ module Verikloak
         )
       end
 
-      validate_not_private!(clean_jwks_uri)
+      validate_not_private!(clean_jwks_uri) unless allow_http
 
       @jwks_uri    = clean_jwks_uri
       @connection  = connection || Verikloak::HTTP.default_connection
@@ -162,6 +162,9 @@ module Verikloak
 
     # Validates that the JWKs URI does not resolve to a private/internal IP address (SSRF protection).
     #
+    # Skipped when `allow_http: true` is set (development mode), since local Keycloak instances
+    # typically run on private/loopback addresses.
+    #
     # The discovery redirect flow already validates redirect targets, but the `jwks_uri` value
     # extracted from the discovery JSON document itself was not previously validated, allowing a
     # compromised or malicious discovery endpoint to point JWKs fetching at internal services.

data/lib/verikloak/token_decoder.rb

@@ -8,7 +8,9 @@ module Verikloak
   # This class validates a JWT's signature and standard claims (`iss`, `aud`, `exp`, `nbf`, etc.)
   # using the appropriate RSA public key selected by the JWT's `kid` header.
   # Only `RS256`-signed tokens with RSA JWKs are supported.
-  # It also supports a configurable clock skew (`leeway`) to account for minor time drift.
+  # It also supports a configurable clock skew (`leeway`) to account for minor time drift,
+  # which is applied uniformly to `exp`, `nbf`, and `iat` (Verikloak applies leeway to
+  # `iat` itself because ruby-jwt 3.x's built-in `iat` validator ignores leeway).
   #
   # @example
   #   decoder = Verikloak::TokenDecoder.new(
@@ -41,7 +43,12 @@ module Verikloak
       @leeway   = leeway
       # Normalize and store verification options
       @options  = symbolize_keys(options || {})
-      @options_without_leeway = @options.except(:leeway).freeze
+      # Remove keys we manage ourselves so user-supplied values don't
+      # re-enable ruby-jwt's built-in (broken w.r.t. leeway) iat validator
+      # via the final merge in #jwt_decode_options. The user's intent for
+      # :leeway / :verify_iat is still honoured by reading from @options
+      # directly elsewhere in this class.
+      @options_for_jwt = @options.except(:leeway, :verify_iat).freeze
 
       # Build a kid-indexed hash for O(1) JWK lookup
       @jwk_by_kid = {}
@@ -118,9 +125,49 @@ module Verikloak
     # @return [Hash] Verified claims (payload).
     def decode_with_public_key(token, public_key)
       payload, = JWT.decode(token, public_key, true, jwt_decode_options)
+      verify_iat_with_leeway!(payload)
       payload
     end
 
+    # Verifies the `iat` (issued-at) claim with the configured leeway tolerance.
+    #
+    # ruby-jwt 3.x's built-in `Claims::IssuedAt` validator does not honor the
+    # `leeway` option; it raises `JWT::InvalidIatError` whenever `iat` is even
+    # a fraction of a second in the future. In OIDC deployments the IdP
+    # (e.g. Keycloak) and the Resource Server typically run on different
+    # hosts/containers with small clock skew, so `iat` is routinely a few
+    # hundred milliseconds to a few seconds in the future relative to the
+    # Resource Server's clock. To provide behaviour consistent with `exp`
+    # and `nbf` (which honor `leeway`), Verikloak performs its own `iat`
+    # check after `JWT.decode` with the configured leeway applied.
+    #
+    # Users may opt out by passing `options: { verify_iat: false }` to the
+    # decoder, in which case this check is skipped entirely.
+    #
+    # @param payload [Hash] Decoded JWT claims.
+    # @return [void]
+    # @raise [TokenDecoderError] code: 'invalid_token' when `iat` is not
+    #   numeric or is further in the future than the allowed leeway.
+    def verify_iat_with_leeway!(payload)
+      return if @options[:verify_iat] == false
+      return unless payload.is_a?(Hash)
+
+      # Support both string- and symbol-keyed payloads. Callers may pass
+      # `options: { symbolize_names: true }` which causes JWT.decode to
+      # return symbol keys; without indifferent lookup we'd silently
+      # skip iat validation while ruby-jwt's check is disabled.
+      return unless payload.key?('iat') || payload.key?(:iat)
+
+      iat = payload.key?('iat') ? payload['iat'] : payload[:iat]
+      leeway = @options.key?(:leeway) ? @options[:leeway] : @leeway
+      leeway = leeway.to_f
+
+      return if iat.is_a?(Numeric) && iat.to_f <= Time.now.to_f + leeway
+
+      raise TokenDecoderError.new('Invalid issued-at (iat) claim',
+                                  code: 'invalid_token')
+    end
+
     # Returns the verification options passed to JWT.decode.
     #
     # Enforces:
@@ -129,6 +176,15 @@ module Verikloak
     # - Expiration (`exp`) and not-before (`nbf`) checks
     # - Clock skew tolerance via `leeway`
     #
+    # NOTE: `verify_iat` is intentionally disabled here. ruby-jwt 3.x's
+    # built-in `iat` validator ignores the `leeway` option, which causes
+    # spurious `JWT::InvalidIatError` failures whenever the IdP clock is
+    # even slightly ahead of the Resource Server's clock. Verikloak
+    # re-implements the `iat` check in {#verify_iat_with_leeway!} so the
+    # configured `leeway` is honoured consistently with `exp` and `nbf`.
+    # Users may still opt out entirely by passing
+    # `options: { verify_iat: false }` to the decoder.
+    #
     # @return [Hash]
     def jwt_decode_options
       base = {
@@ -137,15 +193,17 @@ module Verikloak
         verify_iss: true,
         aud: @audience,
         verify_aud: true,
-        verify_iat: true,
+        # See note above: handled by verify_iat_with_leeway! after decode.
+        verify_iat: false,
         verify_expiration: true,
         verify_not_before: true
       }
       # options[:leeway] overrides top-level @leeway if provided
       leeway = @options.key?(:leeway) ? @options[:leeway] : @leeway
       merged = base.merge(leeway: leeway)
-      # Merge remaining options last (excluding :leeway which is already applied)
-      extra = @options_without_leeway
+      # Merge remaining options last (excluding :leeway and :verify_iat,
+      # which Verikloak manages itself — see initializer comment).
+      extra = @options_for_jwt
       merged.merge(extra)
     end
 

data/lib/verikloak/version.rb

@@ -2,5 +2,5 @@
 
 module Verikloak
   # Defines the current version of the Verikloak gem.
-  VERSION = '1.0.0'
+  VERSION = '1.0.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - taiyaky
@@ -131,7 +131,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak
   changelog_uri: https://github.com/taiyaky/verikloak/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak/1.0.0
+  documentation_uri: https://rubydoc.info/gems/verikloak/1.0.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: