verikloak-rails 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1add58266f9789a0e9263c36d5e33ab80207b02a87b999d22b5fa65b813f5f36
-  data.tar.gz: 58d956084cc1631e4a0854744627dd3ba95350f7a9c1687665b7025fd943addb
+  metadata.gz: 0b1a2ddc3ca2180e8850394cbfbeb31ee7e79347a14b1589fbed46249e282460
+  data.tar.gz: ee5f73e8edc0895ac4f9c999db71bc818e23d609952637c0f5ce17b6d7795517
 SHA512:
-  metadata.gz: 183bb26475f75704c35880db14e67ea5a83a3c3923d3ca8c6788c92e7735a2d00deabb681f0e65b8bf561e2b6a5aa0cfb4e7ccc24760c091dbe0145f87558311
-  data.tar.gz: 24bc9a344903243e2c63015c4429b8ea713467df15636021f91fc4698a39600ecd0a84e9caccac489ffc1e1d809353961170008ceabed24a106ad65e1b720fef
+  metadata.gz: 882290c28579b912a7212ca3183d722d8b1f0e6d44b68f99c983351d4fe57d20fba702f0bf4671f575b1ef7a50b8da9c55f7b08220c264b2af2a6ae07f22814a
+  data.tar.gz: 4188be35ed688f8bb58b0a46a22b0e4e7e4f98218707f2f665c50a265b1e613aad2074114d7ffe0715494d3bd6185463b075989e5e4930e00f238999ee7b2a4d

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [0.2.3] - 2025-09-22
+
+### Changed
+- Provide a safe default audience (`'rails-api'`) so fresh installs keep `Verikloak::Middleware` active and remain compatible with the optional `verikloak-audience` gem.
+
+---
+
+## [0.2.2] - 2025-09-21
+
+### Added
+- Automatically insert `Verikloak::Bff::HeaderGuard` when the optional gem is available, with configuration toggles and ordering controls.
+- Configuration knobs for positioning the base `Verikloak::Middleware` within the Rack stack.
+
+### Changed
+- Disable the built-in Pundit rescue when `verikloak-pundit` is loaded unless explicitly configured.
+
+### Documentation
+- Note related gems in the installer output and README, including new configuration options for middleware ordering and BFF auto-insertion.
+
 ---
 
 ## [0.2.1] - 2025-09-21

data/README.md

@@ -83,9 +83,10 @@ end
 
 ## Middleware
 ### Inserted Middleware
-| Component | Inserted after | Purpose |
+| Component | Inserted relative to | Purpose |
 | --- | --- | --- |
-| `Verikloak::Middleware` | `Rails::Rack::Logger` | Validate Bearer JWT (OIDC discovery + JWKS), set `verikloak.user`/`verikloak.token`, and honor `skip_paths` |
+| `Verikloak::Bff::HeaderGuard` (optional) | Before `Verikloak::Middleware` by default when the gem is present | Normalize or enforce trusted proxy headers such as `X-Forwarded-Access-Token` |
+| `Verikloak::Middleware` | After `Rails::Rack::Logger` by default (configurable) | Validate Bearer JWT (OIDC discovery + JWKS), set `verikloak.user`/`verikloak.token`, and honor `skip_paths` |
 
 ### BFF Integration
 Support for BFF header handling (e.g., normalizing or enforcing `X-Forwarded-Access-Token`) now lives in a dedicated gem: verikloak-bff.
@@ -94,6 +95,8 @@ Note: verikloak-bff's `HeaderGuard` never overwrites an existing `Authorization`
 - Gem: https://github.com/taiyaky/verikloak-bff
 - Rails guide: `docs/rails.md` in that repository
 
+When `verikloak-bff` is on the load path, `verikloak-rails` automatically inserts `Verikloak::Bff::HeaderGuard` before the base middleware so forwarded headers are normalized before verification. Control this via `config.verikloak.auto_insert_bff_header_guard` and the `bff_header_guard_insert_before/after` knobs.
+
 Use verikloak-bff alongside this gem when you front Rails with a BFF/proxy such as oauth2-proxy and need to enforce trusted forwarding and header consistency.
 
 ## Configuration (initializer)
@@ -103,7 +106,7 @@ Keys under `config.verikloak`:
 | Key | Type | Description | Default |
 | --- | --- | --- | --- |
 | `discovery_url` | String | OIDC discovery URL | `nil` |
-| `audience` | String or Array | Expected `aud` | `nil` |
+| `audience` | String or Array | Expected `aud` | `'rails-api'` |
 | `issuer` | String | Expected `iss` | `nil` |
 | `leeway` | Integer | Clock skew allowance (seconds) | `60` |
 | `skip_paths` | Array<String> | Paths to skip verification | `['/up','/health','/rails/health']` |
@@ -111,7 +114,12 @@ Keys under `config.verikloak`:
 | `error_renderer` | Object responding to `render(controller, error)` | Override error rendering | built-in JSON renderer |
 | `auto_include_controller` | Boolean | Auto-include controller concern | `true` |
 | `render_500_json` | Boolean | Rescue `StandardError`, log the exception, and render JSON 500 | `false` |
-| `rescue_pundit` | Boolean | Rescue `Pundit::NotAuthorizedError` to 403 JSON when Pundit is present | `true` |
+| `rescue_pundit` | Boolean | Rescue `Pundit::NotAuthorizedError` to 403 JSON when Pundit is present (auto-disabled when `verikloak-pundit` is loaded) | `true` |
+| `middleware_insert_before` | Object/String/Symbol | Insert `Verikloak::Middleware` before this Rack middleware | `nil` |
+| `middleware_insert_after` | Object/String/Symbol | Insert `Verikloak::Middleware` after this Rack middleware (`Rails::Rack::Logger` when `nil`) | `nil` |
+| `auto_insert_bff_header_guard` | Boolean | Auto insert `Verikloak::Bff::HeaderGuard` when the gem is present | `true` |
+| `bff_header_guard_insert_before` | Object/String/Symbol | Insert the header guard before this middleware (`Verikloak::Middleware` when `nil`) | `nil` |
+| `bff_header_guard_insert_after` | Object/String/Symbol | Insert the header guard after this middleware | `nil` |
 
 Environment variable examples are in the generated initializer.
 
@@ -127,7 +135,10 @@ Rails.application.configure do
   # Optional but recommended when you know it
   # config.verikloak.issuer        = 'https://idp.example.com/realms/myrealm'
 
-  # For BFF/proxy header handling, see verikloak-bff
+  # For BFF/proxy header handling, see verikloak-bff (auto inserted when present)
+  # To customize ordering:
+  # config.verikloak.middleware_insert_before = Rack::Attack
+  # config.verikloak.auto_insert_bff_header_guard = false
 end
 ```
 
@@ -221,8 +232,10 @@ end
 ## Optional Pundit Rescue
 If the `pundit` gem is present, `Pundit::NotAuthorizedError` is rescued to a standardized 403 JSON. This is a lightweight convenience only; deeper Pundit integration (policies, helpers) is out of scope and can live in a separate plugin.
 
+When the optional [`verikloak-pundit`](https://github.com/taiyaky/verikloak-pundit) gem is loaded, the built-in rescue is automatically disabled to avoid double-handling errors. Explicitly set `config.verikloak.rescue_pundit` if you prefer different behavior.
+
 ### Toggle
-Toggle with `config.verikloak.rescue_pundit` (default: true). Environment example:
+Toggle with `config.verikloak.rescue_pundit` (default: true unless overridden by `verikloak-pundit`). Environment example:
 
 ```ruby
 # config/initializers/verikloak.rb

data/lib/generators/verikloak/install/install_generator.rb

@@ -30,6 +30,8 @@ module Verikloak
           2) Set discovery_url / audience in config/initializers/verikloak.rb
           3) (Optional) If you disable auto-include, add this line to ApplicationController:
                include Verikloak::Rails::Controller
+          4) (Optional) For BFF/proxy setups, add gem 'verikloak-bff' to normalize headers.
+          5) (Optional) When using Pundit policies, consider gem 'verikloak-pundit' for richer errors.
         MSG
       end
     end

data/lib/verikloak/rails/configuration.rb

@@ -38,16 +38,34 @@ module Verikloak
     # @!attribute [rw] rescue_pundit
     #   Rescue `Pundit::NotAuthorizedError` and render JSON 403 responses.
     #   @return [Boolean]
+    # @!attribute [rw] middleware_insert_before
+    #   Rack middleware to insert `Verikloak::Middleware` before.
+    #   @return [Object, String, Symbol, nil]
+    # @!attribute [rw] middleware_insert_after
+    #   Rack middleware to insert `Verikloak::Middleware` after.
+    #   @return [Object, String, Symbol, nil]
+    # @!attribute [rw] auto_insert_bff_header_guard
+    #   Auto-insert `Verikloak::Bff::HeaderGuard` when available.
+    #   @return [Boolean]
+    # @!attribute [rw] bff_header_guard_insert_before
+    #   Rack middleware to insert the header guard before.
+    #   @return [Object, String, Symbol, nil]
+    # @!attribute [rw] bff_header_guard_insert_after
+    #   Rack middleware to insert the header guard after.
+    #   @return [Object, String, Symbol, nil]
     class Configuration
       attr_accessor :discovery_url, :audience, :issuer, :leeway, :skip_paths,
                     :logger_tags, :error_renderer, :auto_include_controller,
-                    :render_500_json, :rescue_pundit
+                    :render_500_json, :rescue_pundit,
+                    :middleware_insert_before, :middleware_insert_after,
+                    :auto_insert_bff_header_guard,
+                    :bff_header_guard_insert_before, :bff_header_guard_insert_after
 
       # Initialize configuration with sensible defaults for Rails apps.
       # @return [void]
       def initialize
         @discovery_url = nil
-        @audience      = nil
+        @audience      = 'rails-api'
         @issuer        = nil
         @leeway        = 60
         @skip_paths    = ['/up', '/health', '/rails/health']
@@ -56,6 +74,11 @@ module Verikloak
         @auto_include_controller = true
         @render_500_json = false
         @rescue_pundit = true
+        @middleware_insert_before = nil
+        @middleware_insert_after = nil
+        @auto_insert_bff_header_guard = true
+        @bff_header_guard_insert_before = nil
+        @bff_header_guard_insert_after = nil
       end
 
       # Options forwarded to the base Verikloak Rack middleware.

data/lib/verikloak/rails/railtie.rb

@@ -16,17 +16,8 @@ module Verikloak
       # Apply configuration and insert middleware.
       # @return [void]
       initializer 'verikloak.configure' do |app|
-        Verikloak::Rails.configure do |c|
-          rails_cfg = app.config.verikloak
-          %i[discovery_url audience issuer leeway skip_paths
-             logger_tags error_renderer auto_include_controller
-             render_500_json rescue_pundit].each do |key|
-            c.send("#{key}=", rails_cfg[key]) if rails_cfg.key?(key)
-          end
-        end
-        app.middleware.insert_after ::Rails::Rack::Logger,
-                                    ::Verikloak::Middleware,
-                                    **Verikloak::Rails.config.middleware_options
+        stack = ::Verikloak::Rails::Railtie.send(:configure_middleware, app)
+        ::Verikloak::Rails::Railtie.send(:configure_bff_guard, stack)
       end
 
       # Optionally include the controller concern when ActionController loads.
@@ -36,6 +27,72 @@ module Verikloak
           include Verikloak::Rails::Controller if Verikloak::Rails.config.auto_include_controller
         end
       end
+
+      class << self
+        private
+
+        # Apply configured options and insert the base middleware into the stack.
+        #
+        # @param app [Rails::Application] application being initialized
+        # @return [ActionDispatch::MiddlewareStackProxy] configured middleware stack
+        def configure_middleware(app)
+          apply_configuration(app)
+          base_options = Verikloak::Rails.config.middleware_options
+          stack = app.middleware
+          if (before = Verikloak::Rails.config.middleware_insert_before)
+            stack.insert_before before,
+                                ::Verikloak::Middleware,
+                                **base_options
+          else
+            after = Verikloak::Rails.config.middleware_insert_after || ::Rails::Rack::Logger
+            if after
+              stack.insert_after after,
+                                 ::Verikloak::Middleware,
+                                 **base_options
+            else
+              stack.use ::Verikloak::Middleware, **base_options
+            end
+          end
+          stack
+        end
+
+        # Insert the optional HeaderGuard middleware when verikloak-bff is present.
+        #
+        # @param stack [ActionDispatch::MiddlewareStackProxy]
+        # @return [void]
+        def configure_bff_guard(stack)
+          return unless Verikloak::Rails.config.auto_insert_bff_header_guard
+          return unless defined?(::Verikloak::Bff::HeaderGuard)
+
+          guard_before = Verikloak::Rails.config.bff_header_guard_insert_before
+          guard_after = Verikloak::Rails.config.bff_header_guard_insert_after
+          if guard_before
+            stack.insert_before guard_before, ::Verikloak::Bff::HeaderGuard
+          elsif guard_after
+            stack.insert_after guard_after, ::Verikloak::Bff::HeaderGuard
+          else
+            stack.insert_before ::Verikloak::Middleware, ::Verikloak::Bff::HeaderGuard
+          end
+        end
+
+        # Sync configuration from the Rails application into Verikloak::Rails.
+        #
+        # @param app [Rails::Application]
+        # @return [void]
+        def apply_configuration(app)
+          Verikloak::Rails.configure do |c|
+            rails_cfg = app.config.verikloak
+            %i[discovery_url audience issuer leeway skip_paths
+               logger_tags error_renderer auto_include_controller
+               render_500_json rescue_pundit middleware_insert_before
+               middleware_insert_after auto_insert_bff_header_guard
+               bff_header_guard_insert_before bff_header_guard_insert_after].each do |key|
+              c.send("#{key}=", rails_cfg[key]) if rails_cfg.key?(key)
+            end
+            c.rescue_pundit = false if !rails_cfg.key?(:rescue_pundit) && defined?(::Verikloak::Pundit)
+          end
+        end
+      end
     end
   end
 end

data/lib/verikloak/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Verikloak
   module Rails
-    VERSION = '0.2.1'
+    VERSION = '0.2.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - taiyaky
@@ -9,6 +9,26 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -35,20 +55,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.2.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.2.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
 description: 'Rails integration for Verikloak: auto middleware, helpers, and standardized
   JSON errors.'
 executables: []
@@ -73,7 +93,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-rails
   changelog_uri: https://github.com/taiyaky/verikloak-rails/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-rails/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.2.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.2.3
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: