verikloak 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 743b7db62f39f179fe22804c61144e661992625e43f3b411ea965f85364b6f50
-  data.tar.gz: ea9fea3cc08d53d076c60e946a39dad3594468dc16574b6a1f3a0e4574f9d80c
+  metadata.gz: 24bc2b5eb7f699c9f8bc4970a2b0b6cdca87b7c7e37d9718c51d85d8cf58a8cc
+  data.tar.gz: 439ec2fb34a67140476aff243addfaac8cb8d5ac18ef7b6915d3a9ba6dc5947d
 SHA512:
-  metadata.gz: 89d6398d946686f61ec67dd93a2f807f38b4cc828bf86b4023787ea3aece53ebac95b08306827a06507883d1ef3f1711571af01db0c7ac5e2e4cc5340d92d34b
-  data.tar.gz: 5469a3833cde3b5f5e21439cdd19bb6638ef0e3b49fd2da64e7398dcd24a8851eec11f985ab0821a23b7446d275983b62e87804b541299ec486b88113d8b89ee
+  metadata.gz: 61be82820e149b89c7e5dead4bc79aef1da0959b85ba447e7bf9d6a346efb331f378030620c2ee42d2b41e5c3e21d89346f405ad16b6264f9452fc49771fc2d4
+  data.tar.gz: 9bec7c747971154c59321505fdd2817487e09013eb8e32d3defe86a7dc38a4731c5e01d113639cd3eae1a33e9073b932dfa5d9a243b65a1609d9b3549cb48129

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2025-12-31
+
+### Added
+- **NEW**: `issuer` parameter for `Middleware#initialize` to optionally override the discovered issuer
+  - When provided, the configured issuer takes precedence over the OIDC discovery document's issuer
+  - This enables compatibility with `verikloak-rails` which passes `issuer` from configuration
+  - If not provided, the middleware continues to use the issuer from OIDC discovery (existing behavior)
+
+### Changed
+- Internal issuer handling now distinguishes between `@configured_issuer` (user-provided) and `@issuer` (discovered/effective)
+- When `jwks_cache` is injected, discovery is only fetched once (and skipped entirely if `issuer` is provided)
+
 ## [0.2.1] - 2025-09-23
 
 ### Changed

data/README.md

@@ -41,10 +41,42 @@ Add the middleware in `config/application.rb`:
 ```ruby
 config.middleware.use Verikloak::Middleware,
   discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
-  audience: "your-client-id",
-  skip_paths: ['/skip_path']
+  audience: "your-client-id"
 ```
 
+For production environments, use environment variables:
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  skip_paths: ['/', '/health', '/public/*', '/rails/*']
+```
+
+#### Advanced configuration
+
+For more complex setups, Verikloak supports additional configuration options:
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  issuer: "https://custom.issuer.example.com/realms/myrealm", # Optional: override discovered issuer
+  skip_paths: ['/', '/health', '/public/*', '/rails/*'],
+  leeway: 30, # Allow 30 seconds clock skew
+  token_env_key: "rack.session.token",     # Custom token storage key
+  user_env_key: "rack.session.claims",     # Custom user claims storage key
+  realm: "my-api",                         # Custom realm for WWW-Authenticate header
+  logger: Rails.logger                     # Logger for internal errors
+```
+
+**Additional middleware options:**
+
+- `token_env_key` (default: `"verikloak.token"`) — where the raw JWT is stored in the Rack env
+- `user_env_key` (default: `"verikloak.user"`) — where decoded claims are stored
+- `realm` (default: `"verikloak"`) — value used in the `WWW-Authenticate` header for 401 responses
+- `logger` — an object responding to `error` (and optionally `debug`) that receives unexpected 500-level failures
+
 #### Handling Authentication Failures
 
 When you use the Rack middleware, authentication failures are automatically converted into JSON error responses (for example, `401` for token issues, `503` for JWKs/discovery errors). In most cases **you do not need to add custom `rescue_from` handlers** in Rails controllers.
@@ -84,40 +116,25 @@ All Verikloak errors inherit from `Verikloak::Error`:
 - `Verikloak::JwksCacheError` – JWKs fetch/parse/cache (`503 Service Unavailable`)
 - `Verikloak::MiddlewareError` – header/infra issues surfaced by the middleware (usually `401`, sometimes `503`)
 
-#### Recommended: use environment variables in production
+### Standalone Rack app
 
 ```ruby
-config.middleware.use Verikloak::Middleware,
-  discovery_url: ENV.fetch("DISCOVERY_URL"),
-  audience: ENV.fetch("CLIENT_ID"),
-  skip_paths: ['/', '/health', '/public/*', '/rails/*']
-```
-This makes the configuration secure and flexible across environments.
-
-#### Advanced middleware options
-
-`Verikloak::Middleware` exposes a few optional knobs that help integrate with
-different Rack stacks:
+# config.ru example for a standalone Rack app
+require "verikloak"
 
-- `token_env_key` (default: `"verikloak.token"`) — where the raw JWT is stored in the Rack env
-- `user_env_key` (default: `"verikloak.user"`) — where decoded claims are stored
-- `realm` (default: `"verikloak"`) — value used in the `WWW-Authenticate` header for 401 responses
-- `logger` — an object responding to `error` (and optionally `debug`) that receives unexpected 500-level failures
+use Verikloak::Middleware,
+  discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
+  audience: "my-client-id"
 
-```ruby
-config.middleware.use Verikloak::Middleware,
-  discovery_url: ENV.fetch("DISCOVERY_URL"),
-  audience: ENV.fetch("CLIENT_ID"),
-  token_env_key: "rack.session.token",
-  user_env_key: "rack.session.claims",
-  realm: "my-api",
-  logger: Rails.logger
+run ->(env) {
+  user = env["verikloak.user"] # Decoded JWT claims hash (if token is valid)
+  [200, { "Content-Type" => "application/json" }, [user.to_json]]
+}
 ```
 
 ### Accessing claims in controllers
 
-Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment.  
-You can access them in any Rails controller:
+Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment:
 
 ```ruby
 class Api::V1::NotesController < ApplicationController
@@ -131,22 +148,6 @@ class Api::V1::NotesController < ApplicationController
 end
 ```
 
-### Standalone Rack app
-
-```ruby
-# config.ru example for a standalone Rack app
-require "verikloak"
-
-use Verikloak::Middleware,
-  discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
-  audience: "my-client-id"
-
-run ->(env) {
-  user = env["verikloak.user"] # Decoded JWT claims hash (if token is valid)
-  [200, { "Content-Type" => "application/json" }, [user.to_json]]
-}
-```
-
 ## How It Works
 
 1. Extracts the `Authorization: Bearer <token>` header
@@ -194,26 +195,7 @@ Verikloak returns JSON error responses in a consistent format with structured er
 }
 ```
 
-```json
-{
-  "error": "jwks_parse_failed",
-  "message": "Failed to parse JWKs"
-}
-```
-
-```json
-{
-  "error": "discovery_metadata_fetch_failed",
-  "message": "Failed to fetch OIDC discovery document"
-}
-```
-
-```json
-{
-  "error": "discovery_metadata_invalid",
-  "message": "Failed to parse OIDC discovery document"
-}
-```
+For a full list of error cases and detailed explanations, please see the [ERRORS.md](ERRORS.md) file.
 
 ### Error Types
 
@@ -223,30 +205,29 @@ Verikloak returns JSON error responses in a consistent format with structured er
 | `expired_token`            | 401 Unauthorized          | The token has expired                                                                        |
 | `missing_authorization_header` | 401 Unauthorized      | The `Authorization` header is missing                                                        |
 | `invalid_authorization_header` | 401 Unauthorized      | The `Authorization` header format is invalid                                                 |
-| `unsupported_algorithm`    | 401 Unauthorized          | The token’s signing algorithm is not supported                                               |
+| `unsupported_algorithm`    | 401 Unauthorized          | The token's signing algorithm is not supported                                               |
 | `invalid_signature`        | 401 Unauthorized          | The token signature could not be verified                                                    |
 | `invalid_issuer`           | 401 Unauthorized          | Invalid `iss` claim                                                                          |
 | `invalid_audience`         | 401 Unauthorized          | Invalid `aud` claim                                                                          |
 | `not_yet_valid`            | 401 Unauthorized          | The token is not yet valid (`nbf` in the future)                                             |
-| `jwks_fetch_failed`        | 503 Service Unavailable   | Failed to fetch JWKs                                                                    |
-| `jwks_parse_failed`        | 503 Service Unavailable   | Failed to parse JWKs                                                                    |
+| `jwks_fetch_failed`        | 503 Service Unavailable   | Failed to fetch JWKs                                                                         |
+| `jwks_parse_failed`        | 503 Service Unavailable   | Failed to parse JWKs                                                                         |
 | `jwks_cache_miss`          | 503 Service Unavailable   | JWKs cache is empty (e.g., 304 Not Modified without prior cache)                             |
 | `discovery_metadata_fetch_failed` | 503 Service Unavailable   | Failed to fetch OIDC discovery document                                               |
-| `discovery_metadata_invalid` | 503 Service Unavailable   | Failed to parse OIDC discovery document                                                    |
+| `discovery_metadata_invalid` | 503 Service Unavailable   | Failed to parse OIDC discovery document                                                     |
 | `discovery_redirect_error` | 503 Service Unavailable   | Discovery response was a redirect without a valid Location header                           |
 | `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.  
 > It may raise `invalid_signature`, `unsupported_algorithm`, `expired_token`, `invalid_issuer`, `invalid_audience`, or `not_yet_valid` depending on the verification outcome.
 
-For a full list of error cases and detailed explanations, please see the [ERRORS.md](ERRORS.md) file.
-
 ## Configuration Options
 
 | Key             | Required | Description                                 |
 | --------------- | -------- | ------------------------------------------- |
 | `discovery_url` | Yes   | Full URL to your realm's OIDC discovery doc |
 | `audience`      | Yes   | Your client ID (checked against `aud`). Accepts a String or callable returning a String/Array per request. |
+| `issuer`        | No       | Optional override for the expected `iss` claim; defaults to the discovery `issuer`. |
 | `skip_paths`    | No       | Array of paths or wildcards to skip authentication, e.g. `['/', '/health', '/public/*']`. **Note:** Regex patterns are not supported. |
 | `discovery`     | No       | Inject custom Discovery instance (advanced/testing) |
 | `jwks_cache`    | No       | Inject custom JwksCache instance (advanced/testing) |
@@ -254,6 +235,10 @@ For a full list of error cases and detailed explanations, please see the [ERRORS
 | `token_verify_options` | No | Hash of advanced JWT verification options passed through to TokenDecoder. For example: `{ verify_iat: false, leeway: 10, algorithms: ["RS256"] }`. If both `leeway:` and `token_verify_options[:leeway]` are set, the latter takes precedence. |
 | `decoder_cache_limit` | No | Maximum number of `TokenDecoder` instances retained per middleware. Defaults to `128`. Set to `0` to disable caching or `nil` for an unlimited cache. |
 | `connection`   | No       | Inject a Faraday::Connection used for both Discovery and JWKs fetches. Defaults to a safe connection with timeouts and retries. |
+| `token_env_key` | No       | Rack env key for the raw JWT. Defaults to `verikloak.token`. |
+| `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`). |
 
 #### Option: `skip_paths`
 
@@ -273,7 +258,7 @@ skip_paths: ['/', '/health', '/rails/*', '/public/src']
 Paths **not matched** by any `skip_paths` entry will require a valid JWT.
 
 **Note:** Regex patterns are not supported. Only literal paths and `*` wildcards are allowed.  
-Internally, `*` expands to match nested paths, so patterns like `/rails/*` are valid. This differs from regex — for example, `'/rails'` alone matches only `/rails`, while `'/rails/*'` covers both `/rails` and deeper subpaths.
+Internally, `*` expands to match nested paths, so patterns like `/rails/*` are valid. This differs from regex; for example, `'/rails'` alone matches only `/rails`, while `'/rails/*'` covers both `/rails` and deeper subpaths.
 
 #### Option: `audience`
 
@@ -343,6 +328,8 @@ config.middleware.use Verikloak::Middleware,
 - `token_verify_options:` is passed directly to TokenDecoder (and ultimately to `JWT.decode`).
 - If both are set, `token_verify_options[:leeway]` takes precedence.
 
+## Performance & Caching
+
 #### Decoder cache & performance
 
 Internally, Verikloak caches `TokenDecoder` instances per JWKs fetch to avoid reinitializing

data/lib/verikloak/middleware.rb

@@ -489,9 +489,14 @@ module Verikloak
         previous_keys_id = cached_keys_identity(@jwks_cache)
         if @jwks_cache.nil?
           config   = @discovery.fetch!
-          @issuer  = config['issuer']
+          # Use configured issuer if provided, otherwise use discovered issuer
+          @issuer  = @configured_issuer || config['issuer']
           jwks_uri = config['jwks_uri']
           @jwks_cache = JwksCache.new(jwks_uri: jwks_uri, connection: @connection)
+        elsif @configured_issuer.nil? && @issuer.nil?
+          # If jwks_cache was injected but no issuer configured and not yet discovered, fetch discovery to set issuer
+          config = @discovery.fetch!
+          @issuer = config['issuer']
         end
 
         @jwks_cache.fetch!
@@ -633,6 +638,7 @@ module Verikloak
     # @param discovery_url [String] OIDC discovery endpoint URL
     # @param audience [String, #call] Expected `aud` claim. When a callable is provided it
     #   receives the Rack env and may return a String or Array of audiences.
+    # @param issuer [String, nil] Optional issuer override (defaults to discovery `issuer`)
     # @param skip_paths [Array<String>] literal paths or wildcard patterns to bypass auth
     # @param discovery [Discovery, nil] custom discovery instance (for DI/tests)
     # @param jwks_cache [JwksCache, nil] custom JWKs cache instance (for DI/tests)
@@ -648,6 +654,7 @@ module Verikloak
     def initialize(app,
                    discovery_url:,
                    audience:,
+                   issuer: nil,
                    skip_paths: [],
                    discovery: nil,
                    jwks_cache: nil,
@@ -667,7 +674,10 @@ module Verikloak
       @leeway = leeway
       @token_verify_options = token_verify_options || {}
       @decoder_cache_limit = normalize_decoder_cache_limit(decoder_cache_limit)
-      @issuer        = nil
+      # Optional user-configured issuer (overrides discovery issuer when provided)
+      @configured_issuer = issuer
+      # Effective issuer; may be nil initially and set via discovery if not configured
+      @issuer        = @configured_issuer
       @mutex         = Mutex.new
       @decoder_cache = {}
       @decoder_cache_order = []

data/lib/verikloak/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - taiyaky
@@ -109,7 +109,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/0.2.1
+  documentation_uri: https://rubydoc.info/gems/verikloak/0.3.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: