verikloak-bff 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 459eed20d30ee0052dda42e6e1b18c4ac4f58aa897ba24a0090d19931a28690e
-  data.tar.gz: 20d3f106c2439d3f63b683a79f900d9c072893ec730d9d294e610817b560777e
+  metadata.gz: edf579dc8e103482358c6ef7577c90c0b4aa24ae53b31c0c82bf89e5ffb4a68a
+  data.tar.gz: b976af45f7ffef721bd69263ed29cafaea1fdd711a1f94fff75a0045af8fc648
 SHA512:
-  metadata.gz: 47838af8ec9b12a4570e967c188ffcaf7a4ce9556aa06409d6fce1906bc4fd0b16568342baacec85a46883f9161fe015459996453e724e37c7c6a6d7e339e1c8
-  data.tar.gz: b12bcca4f52ba05a8aba8fe145c1664743e70127120642f7bf334aa8db1499301badd988d5a92040d359fc2e61f94d1bbf79699f972fc7f05c12867702a10e72
+  metadata.gz: 2354503e6faf4768d680057ae347e44d5e0eadfe29ef49f01585a0db859addcb53f881e49f73956e07721799534ac444c2ae13f6c9ac93983256d4d61bdaad0d
+  data.tar.gz: 6543a6dd768d1cd2d11fe71a976dcbbd52bd1ad40021177a7b798dfd4b20b9560384b13cc1f1adb861b61865f5a076b746999d7939b225b65a54bda2249106dd

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.6] - 2025-12-31
+
+### Fixed
+- **Rails 8.x+ compatibility**: Remove `after_initialize` middleware insertion from generator template to avoid `FrozenError` when middleware stack is frozen.
+
+### Changed
+- Generator (`rails g verikloak:bff:install`) now creates a **configuration-only** initializer. Middleware insertion is handled automatically by `verikloak-rails`.
+- Generated initializer includes comprehensive configuration options with documentation comments.
+- **Breaking**: Minimum `verikloak` dependency raised from `>= 0.2.0` to `>= 0.3.0`.
+
+### Documentation
+- Add "Rails Integration" section explaining automatic middleware detection with `verikloak-rails`.
+- Add warning about Rails 8.x+ middleware stack freeze in `after_initialize`.
+- Add "oauth2-proxy Integration" section with header configuration reference and recommended settings.
+- Document manual middleware setup option for users not using `verikloak-rails`.
+- Update `docs/rails.md` with clearer setup instructions and Rails 8.x support note.
+
+## [0.2.5] - 2025-09-28
+
+### Changed
+- Align the install generator under `Verikloak::Bff::Generators` while retaining the `Verikloak::BFF::Generators` alias to avoid constant redefinition warnings during reloads.
+
+
 ## [0.2.4] - 2025-09-27
 
 ### Changed

data/README.md

@@ -31,16 +31,25 @@ use Verikloak::BFF::HeaderGuard, trusted_proxies: ['127.0.0.1', '10.0.0.0/8']
 ```
 
 ### Rails Applications
-Add the gem to your Gemfile and run the install generator to drop an initializer that wires the middleware into Rails:
+Add both gems to your Gemfile:
 ```ruby
+gem 'verikloak-rails'
 gem 'verikloak-bff'
 ```
 
+Run the install generator to create a configuration file:
 ```sh
 bin/rails g verikloak:bff:install
 ```
 
-The generated initializer inserts `Verikloak::BFF::HeaderGuard` after the core `Verikloak::Middleware` during boot. If the core middleware is not present (for example, when verikloak-rails has not been fully configured yet), the initializer logs a warning and allows Rails to boot normally.
+The generator creates `config/initializers/verikloak_bff.rb` with BFF configuration options. **Edit this file to set `trusted_proxies`** (required) and customize other options as needed.
+
+**Note**: Middleware insertion is handled automatically by `verikloak-rails`. The generated initializer only contains configuration—no manual middleware setup is required.
+
+> **Without verikloak-rails**: You can also configure middleware manually in `config/application.rb`:
+> ```ruby
+> config.middleware.insert_before Verikloak::Middleware, Verikloak::BFF::HeaderGuard
+> ```
 
 For detailed configuration, proxy setup examples, and troubleshooting, see [docs/rails.md](docs/rails.md).
 
@@ -110,6 +119,95 @@ For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see [docs/r
 - Claims consistency modes
   - Default `:enforce` mode rejects requests with mismatches. Switch to `claims_consistency_mode: :log_only` when you only need observability signals; downstream services must continue verifying JWT signatures, issuer, audience, and expirations.
 
+## Rails Integration
+
+### Recommended: Use with verikloak-rails (Auto-detection)
+
+When both `verikloak-rails` and `verikloak-bff` are installed, the railtie automatically inserts the BFF middleware. No manual configuration is required.
+
+```ruby
+# Gemfile
+gem 'verikloak-rails'
+gem 'verikloak-bff'
+```
+
+The middleware stack will be configured as:
+```
+[Verikloak::BFF::HeaderGuard] → [Verikloak::Middleware] → [Your App]
+```
+
+### ⚠️ Rails 8.x+ Middleware Stack Freeze
+
+In Rails 8.x and later, the middleware stack is frozen after the `after_initialize` callback. Manual middleware insertion in `after_initialize` will raise `FrozenError`:
+
+```ruby
+# ❌ This will NOT work in Rails 8.x+
+Rails.application.config.after_initialize do
+  Rails.application.config.middleware.insert_after(
+    Verikloak::Middleware,
+    Verikloak::BFF::HeaderGuard
+  )
+end
+# => FrozenError: can't modify frozen Array
+```
+
+**Solution**: Use the automatic detection feature with `verikloak-rails`, or insert middleware in `config/application.rb` or an initializer (which runs before the stack is frozen):
+
+```ruby
+# ✅ This works - config/application.rb
+module MyApp
+  class Application < Rails::Application
+    config.middleware.insert_before Verikloak::Middleware, Verikloak::BFF::HeaderGuard
+  end
+end
+```
+
+## oauth2-proxy Integration
+
+### Header Configuration Reference
+
+| oauth2-proxy Setting | Header Sent | HeaderGuard Behavior |
+|---------------------|-------------|---------------------|
+| `--pass-access-token=true` | Cookie (`_oauth2_proxy`) | Not supported (cookie-based) |
+| `--pass-access-token=true` + nginx | `X-Forwarded-Access-Token` | Normalized to `Authorization` (default) |
+| `--set-authorization-header=true` | `Authorization: Bearer <token>` | Used directly |
+| `--set-xauthrequest=true` | `X-Auth-Request-Access-Token` | Requires `token_header_priority` config |
+
+### Recommended oauth2-proxy Configuration
+
+For best compatibility, configure oauth2-proxy to emit `X-Forwarded-Access-Token` via nginx:
+
+```bash
+oauth2-proxy \
+  --pass-access-token=true \
+  --set-authorization-header=false \
+  --set-xauthrequest=true \
+  --upstream=http://rails-api:3000
+```
+
+Then configure nginx to relay the token:
+
+```nginx
+proxy_set_header X-Forwarded-Access-Token $upstream_http_x_auth_request_access_token;
+```
+
+### Using X-Auth-Request-Access-Token Directly
+
+If you prefer to use `X-Auth-Request-Access-Token` without nginx relay, configure both `forwarded_header_name` and `token_header_priority`:
+
+```ruby
+use Verikloak::BFF::HeaderGuard,
+  trusted_proxies: ['10.0.0.0/8'],
+  # Set the forwarded header to X-Auth-Request-Access-Token
+  forwarded_header_name: 'HTTP_X_AUTH_REQUEST_ACCESS_TOKEN',
+  # Also add to priority list for Authorization seeding
+  token_header_priority: ['HTTP_X_AUTH_REQUEST_ACCESS_TOKEN']
+```
+
+> **Note**: If you only set `token_header_priority` without changing `forwarded_header_name`, 
+> `require_forwarded_header: true` will still expect `X-Forwarded-Access-Token` and return 401 
+> when it's missing.
+
 ## Development (for contributors)
 Clone and install dependencies:
 

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

@@ -1,42 +1,27 @@
 # frozen_string_literal: true
 
-require 'rails/generators/base'
+require 'rails/generators'
 
 module Verikloak
-  module BFF
-    # Namespace for Rails generators related to Verikloak BFF
+  module Bff
+    # Rails generators supporting verikloak-bff integration.
     module Generators
-      # Rails generator for installing Verikloak BFF middleware integration.
-      #
-      # This generator creates a Rails initializer that safely inserts the
-      # Verikloak::BFF::HeaderGuard middleware into the Rails middleware stack.
-      # It replaces automatic middleware insertion to avoid boot failures when
-      # core Verikloak middleware is not yet configured.
-      #
-      # @example Basic usage
-      #   rails g verikloak:bff:install
-      #
-      # @example Custom initializer path
-      #   rails g verikloak:bff:install --initializer=config/initializers/custom_bff.rb
+      # Generator to install the Verikloak BFF initializer into a Rails app.
       #
       # @see Verikloak::BFF::Rails::Middleware
+      # @example Default usage
+      #   rails g verikloak:bff:install
       class InstallGenerator < ::Rails::Generators::Base
         source_root File.expand_path('templates', __dir__)
+        desc 'Creates the Verikloak BFF initializer for Rails applications.'
 
-        # Configuration option for specifying the initializer file path.
-        #
         # @option options [String] :initializer ('config/initializers/verikloak_bff.rb')
-        #   The path where the initializer file will be created
+        #   Path for the generated initializer file.
         class_option :initializer, type: :string,
                                    default: 'config/initializers/verikloak_bff.rb',
                                    desc: 'Path for the generated initializer'
 
-        # Creates the Rails initializer file from template.
-        #
-        # Generates a Rails initializer that safely inserts the HeaderGuard
-        # middleware into the middleware stack with proper error handling.
-        # The initializer uses Verikloak::BFF::Rails::Middleware.insert_after_core
-        # to ensure graceful handling when core middleware is missing.
+        # Copies the initializer template to the desired location.
         #
         # @return [void]
         def create_initializer
@@ -46,3 +31,11 @@ module Verikloak
     end
   end
 end
+
+# Maintain legacy constant path for consumers referencing Verikloak::BFF::Generators.
+module Verikloak
+  # Legacy namespace alias for backward compatibility.
+  module BFF
+    Generators = Bff::Generators unless defined?(Generators)
+  end
+end

data/lib/generators/verikloak/bff/install/templates/initializer.rb.erb

@@ -1,11 +1,115 @@
 # frozen_string_literal: true
 
-# Configure verikloak-bff to insert its HeaderGuard middleware only after the
-# Verikloak core middleware is present. This avoids boot errors when the core
-# gem has not yet been installed.
-Rails.application.config.after_initialize do
-  Verikloak::BFF::Rails::Middleware.insert_after_core(
-    Rails.application.config.middleware,
-    logger: Rails.logger
-  )
+# Verikloak BFF Configuration
+#
+# This file configures the Verikloak::BFF::HeaderGuard middleware.
+#
+# IMPORTANT: Middleware insertion is handled automatically by verikloak-rails.
+# Make sure you have both gems in your Gemfile:
+#
+#   gem 'verikloak-rails'
+#   gem 'verikloak-bff'
+#
+# The middleware stack will be configured as:
+#   [Verikloak::BFF::HeaderGuard] → [Verikloak::Middleware] → [Your App]
+#
+# If you are NOT using verikloak-rails, you must manually insert the middleware
+# in config/application.rb (NOT in after_initialize, which causes FrozenError in Rails 8.x+):
+#
+#   config.middleware.insert_before Verikloak::Middleware, Verikloak::BFF::HeaderGuard
+#
+Verikloak::BFF.configure do |config|
+  # ==========================================================================
+  # Trust Boundary (REQUIRED)
+  # ==========================================================================
+  # Allowlist for trusted proxy peers. Requests from untrusted peers are rejected.
+  # Supports IP addresses, CIDR ranges, Regexp, or Proc.
+  #
+  # SECURITY: Keep this list as specific as possible. Review whenever proxy
+  # topology changes to avoid unintentionally widening the trust boundary.
+  #
+  config.trusted_proxies = ENV.fetch('TRUSTED_PROXIES', '127.0.0.1').split(',').map(&:strip)
+
+  # ==========================================================================
+  # Peer Selection
+  # ==========================================================================
+  # How to determine the client's peer IP for trust decisions.
+  #
+  # :remote_then_xff (default) - Prefer REMOTE_ADDR, then fall back to XFF
+  # :xff_only                  - Use only X-Forwarded-For header
+  #
+  # config.peer_preference = :remote_then_xff
+
+  # Which X-Forwarded-For entry to use when multiple proxies are involved.
+  #
+  # :rightmost (default) - Nearest proxy (recommended for most setups)
+  # :leftmost            - Original client (use only if you trust all proxies)
+  #
+  # config.xff_strategy = :rightmost
+
+  # ==========================================================================
+  # Token Selection & Header Handling
+  # ==========================================================================
+  # Prefer X-Forwarded-Access-Token over Authorization header.
+  #
+  # config.prefer_forwarded = true
+
+  # Reject requests without X-Forwarded-Access-Token (blocks direct access).
+  # Enable this to ensure all requests go through the BFF proxy.
+  #
+  # config.require_forwarded_header = false
+
+  # Require Authorization and X-Forwarded-Access-Token to contain the same token
+  # when both are present.
+  #
+  # config.enforce_header_consistency = true
+
+  # Remove external X-Auth-Request-* headers before passing downstream.
+  # Prevents header injection attacks.
+  #
+  # config.strip_suspicious_headers = true
+
+  # ==========================================================================
+  # Claims Consistency (Optional)
+  # ==========================================================================
+  # Compare X-Auth-Request-* headers against JWT claims.
+  # Useful for detecting token substitution attacks.
+  #
+  # config.enforce_claims_consistency = {
+  #   email: :email,           # X-Auth-Request-Email == JWT email claim
+  #   user: :sub,              # X-Auth-Request-User == JWT sub claim
+  #   groups: :realm_roles     # X-Auth-Request-Groups ⊆ JWT realm_access.roles
+  # }
+
+  # :enforce (default) - Reject mismatches with 403
+  # :log_only          - Log mismatches but allow request to proceed
+  #
+  # config.claims_consistency_mode = :enforce
+
+  # ==========================================================================
+  # Header Name Customization
+  # ==========================================================================
+  # Customize forwarded token header name (if your proxy uses a different header).
+  #
+  # config.forwarded_header_name = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+
+  # Customize X-Auth-Request-* header names.
+  #
+  # config.auth_request_headers = {
+  #   email:  'HTTP_X_AUTH_REQUEST_EMAIL',
+  #   user:   'HTTP_X_AUTH_REQUEST_USER',
+  #   groups: 'HTTP_X_AUTH_REQUEST_GROUPS'
+  # }
+
+  # Priority list for seeding Authorization header when empty.
+  #
+  # config.token_header_priority = ['HTTP_X_FORWARDED_ACCESS_TOKEN']
+
+  # ==========================================================================
+  # Logging
+  # ==========================================================================
+  # Structured logging hook for observability.
+  # Payload includes: rid (request_id), sub, kid, iss, aud
+  #
+  # config.log_with = ->(payload) { Rails.logger.info(payload.to_json) }
 end

data/lib/verikloak/bff/version.rb

@@ -5,6 +5,6 @@
 # @return [String]
 module Verikloak
   module BFF
-    VERSION = '0.2.4'
+    VERSION = '0.2.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - taiyaky
@@ -55,7 +55,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -65,7 +65,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -101,7 +101,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-bff
   changelog_uri: https://github.com/taiyaky/verikloak-bff/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-bff/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.4
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.6
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: