verikloak-rails 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dda87b3f2293f4c0cf05710290a503fd5c15712758f685987385d1b0677938cc
-  data.tar.gz: a299ad22f31b4871fde437e026557b106134e32dece4e7cb45be4073d0269a48
+  metadata.gz: e588f4e83d324112c789986e02a9a2acab3de3a06a1b5f516da2fefe9439e4b4
+  data.tar.gz: e1e59805c5af304ecf4349f5d2031faa79a7e7b5c13188dd32e7866a4f42eb0d
 SHA512:
-  metadata.gz: '0149e3053f208dd90c26ec07a960ff14969cdcda74400403f4ab02376110b31624189b6612bf2d6d3d7857c15d1c2b3190da9b472c487d9a3866eaf4de3aa8f7'
-  data.tar.gz: 2fa3507b18f362cb3523332256a0608bd95564e0a0e0dfb4a17b97b9fafbdb1ddad31fa34bbe8788d52546e1f22dd43b97174ce1474c24385838fef743f5b8ae
+  metadata.gz: 4af9b198e39240cc234c96b897549f893680a45f45223cc0bd9c09ad40139627e8f01a8fb5374c517adadf28aaaee498d189d765eab33ba5a9e5bf42b4e748ed
+  data.tar.gz: 77a17a8d8a44d3b92d8dee19b5e9e7940cd2ddc676166790a5c17cc8ba5064690db080b563b0d38ea7a9ef3ac75e977f6328d0e5cb8c41dd13c6710dc51a83da

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+
+### Changed
+- Simplify `with_required_audience!` to always raise `Verikloak::Error`, letting the shared handler render forbidden responses
+
+### Fixed
+- Ensure the 500 JSON renderer logs exceptions against the actual Rails logger even when wrapped by tagged logging adapters
+
+### Documentation
+- Describe the `rescue_pundit` configuration flag and default initializer settings
+
 ## [0.2.0] - 2025-09-14
 
 ### Breaking

data/README.md

@@ -40,7 +40,7 @@ Then configure `config/initializers/verikloak.rb`.
 | `current_user_claims` | Verified JWT claims (string keys) | `Hash` or `nil` | — |
 | `current_subject` | Convenience accessor for `sub` claim | `String` or `nil` | — |
 | `current_token` | Raw Bearer token from the request | `String` or `nil` | — |
-| `with_required_audience!(*aud)` | Enforce that `aud` includes all required entries | `void` | Renders standardized 403 JSON when requirements are not met |
+| `with_required_audience!(*aud)` | Enforce that `aud` includes all required entries | `void` | Raises `Verikloak::Error('forbidden')` so the concern renders standardized 403 JSON and halts the action |
 
 ### Data Sources
 | Value | Rack env keys | Fallback (RequestStore) | Notes |
@@ -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)
@@ -110,8 +113,13 @@ Keys under `config.verikloak`:
 | `logger_tags` | Array<Symbol> | Tags to add to Rails logs. Supports `:request_id`, `:sub` | `[:request_id, :sub]` |
 | `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` and render JSON 500 | `false` |
-| `rescue_pundit` | Boolean | Rescue `Pundit::NotAuthorizedError` to 403 JSON when Pundit is present | `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 (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

@@ -35,11 +35,34 @@ module Verikloak
     # @!attribute [rw] render_500_json
     #   Rescue StandardError and render a JSON 500 response.
     #   @return [Boolean]
+    # @!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
@@ -51,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/controller.rb

@@ -16,7 +16,8 @@ module Verikloak
         before_action :authenticate_user!
         # Register generic error handler first so specific handlers take precedence.
         if Verikloak::Rails.config.render_500_json
-          rescue_from StandardError do |_e|
+          rescue_from StandardError do |e|
+            _verikloak_log_internal_error(e)
             render json: { error: 'internal_server_error', message: 'An unexpected error occurred' },
                    status: :internal_server_error
           end
@@ -84,13 +85,14 @@ module Verikloak
       #
       # @param required [Array<String>] one or more audiences to require
       # @return [void]
+      # @raise [Verikloak::Error] when the required audience is missing
       # @example
       #   with_required_audience!('my-api', 'payments')
       def with_required_audience!(*required)
         aud = Array(current_user_claims&.dig('aud'))
         return if required.flatten.all? { |r| aud.include?(r) }
 
-        render json: { error: 'forbidden', message: 'Required audience not satisfied' }, status: :forbidden
+        raise ::Verikloak::Error.new('forbidden', 'Required audience not satisfied')
       end
 
       private
@@ -118,10 +120,50 @@ module Verikloak
         end
         if Verikloak::Rails.config.logger_tags.include?(:sub)
           sub = current_subject
-          tags << "sub:#{sub}" if sub
+          if sub
+            sanitized = sub.to_s.gsub(/[[:cntrl:]]+/, ' ').strip
+            tags << "sub:#{sanitized}" unless sanitized.empty?
+          end
         end
         tags
       end
+
+      # Write StandardError details to the controller or Rails logger when
+      # rendering the generic 500 JSON response. Logging ensures the
+      # underlying failure is still visible to operators even though the
+      # response body is static.
+      #
+      # @param exception [Exception]
+      # @return [void]
+      def _verikloak_log_internal_error(exception)
+        target_logger = _verikloak_base_logger
+        return unless target_logger.respond_to?(:error)
+
+        target_logger.error("[Verikloak] #{exception.class}: #{exception.message}")
+        backtrace = exception.backtrace
+        target_logger.error(backtrace.join("\n")) if backtrace&.any?
+      rescue StandardError
+        # Never allow logging failures to interfere with request handling.
+        nil
+      end
+
+      # Locate the innermost logger that responds to `error`.
+      # @return [Object, nil]
+      def _verikloak_base_logger
+        root_logger = if defined?(::Rails) && ::Rails.respond_to?(:logger)
+                        ::Rails.logger
+                      elsif respond_to?(:logger)
+                        logger
+                      end
+        current = root_logger
+        while current.respond_to?(:logger)
+          next_logger = current.logger
+          break if next_logger.nil? || next_logger.equal?(current)
+
+          current = next_logger
+        end
+        current
+      end
     end
   end
 end

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.0'
+    VERSION = '0.2.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - taiyaky
@@ -35,20 +35,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !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.1.5
     - - "<"
       - !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 +73,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.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/0.2.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: