omniauth_openid_federation 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff53053ffcbf2f63f91ae342158b5f11e881f3466c8d1ec1a25c06c8d1ff6b9b
-  data.tar.gz: d11bdc15e0dbbbd710cee19ac670a7425af0f3e37e42765c93df9d4dfac224ac
+  metadata.gz: e299269e65c33735c84f2bec3ee0164bc5cb136c8dac5088be188998d826d5bc
+  data.tar.gz: c35464efdf1af7957456641275cfa3a374a1600a0570fa7db7a6ceeb1a31417f
 SHA512:
-  metadata.gz: '082caf05aaf09898c6bd992f9280570dec07ad19acedf59dcfbf8c60e74af84f03e9f140eab5d4fe4156e97d418bf5c77d623026923d4f748889cc18e555101d'
-  data.tar.gz: 27db7564021a934505269f60bb08eb1eba84eb763b9ea5fd6c06815e4e92cd72cbefed49779d15b9bb872c729525ec3ae3760204ce1948673e708a3ae0e1f655
+  metadata.gz: 9e96511bd8c6972d774435015822297a44892e263b13187ef1a52741186288bf25ded9b15bb0f3c5d856796e7e3b30df9d845c5c3f67987bf7fcd94160c26eda
+  data.tar.gz: 6c5a94f3bb8f429cc9dd583b98032418858520cc93658e9fdba1fe7192d8cb03b9b7e11575d22f44ce5e18cd2cf7bf05f5d512d7a7f96a47404dde00445923e9

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## 1.2.0 (2025-11-27)
+
+- Created `OmniauthOpenidFederation::Engine` class inheriting from `Rails::Engine`
+- Engine provides controllers via standard Rails autoloading mechanisms
+- Routes are now defined in Engine's `config/routes.rb` file
+- Routes must now be mounted using `mount OmniauthOpenidFederation::Engine => "/"` in `config/routes.rb`
+- `FederationEndpoint.mount_routes` is still available for backward compatibility
+
+## 1.1.0 (2025-11-26)
+
+- Enhanced instrumentation: All blocking exceptions automatically reported through instrumentation system, including OmniAuth middleware errors (like AuthenticityTokenProtection)
+- CSRF protection instrumentation: New authenticity_error event type for reporting OmniAuth CSRF protection failures
+- Comprehensive error reporting: Override fail! method in strategy to catch and instrument all authentication failures
+- CSRF protection documentation: Added comprehensive Step 7 in README explaining CSRF protection configuration for both request and callback phases
+- CSRF configuration examples: Added complete examples in examples/config/initializers/devise.rb.example and examples/app/controllers/users/omniauth_callbacks_controller.rb.example
+- Deprecation warnings: Added runtime deprecation warnings for json_jwt method and ftn_spname option to guide users to recommended alternatives
+- Code cleanup: Removed deprecated load_signing_key method (unused, returned nil)
+- Updated deprecation notices: Fixed deprecation notices to reference correct replacement methods (request_object_params instead of non-existent provider_extension_params)
+- Renamed option: `allow_authorize_params` → `request_object_params` for clarity (uses RFC 9101 terminology, clearly indicates params go into JWT request object)
+
 ## 1.0.0 (2025-11-26)
 
 - Initial public release, production-ready

data/README.md

@@ -1,6 +1,6 @@
 # omniauth_openid_federation
 
-[![Gem Version](https://badge.fury.io/rb/omniauth_openid_federation.svg)](https://badge.fury.io/rb/omniauth_openid_federation) [![Test Status](https://github.com/amkisko/omniauth_openid_federation.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/omniauth_openid_federation.rb/actions/workflows/test.yml)
+[![Gem Version](https://badge.fury.io/rb/omniauth_openid_federation.svg?v=1.1.0)](https://badge.fury.io/rb/omniauth_openid_federation) [![Test Status](https://github.com/amkisko/omniauth_openid_federation.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/omniauth_openid_federation.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/omniauth_openid_federation.rb/graph/badge.svg?token=CX3O9M1GIT)](https://codecov.io/gh/amkisko/omniauth_openid_federation.rb)
 
 OmniAuth strategy for OpenID Federation providers with comprehensive security features, supporting signed request objects, ID token encryption, and full OpenID Federation 1.0 compliance.
 
@@ -128,6 +128,8 @@ config.omniauth :openid_federation,
 - `entity_statement_path` is optional - only for offline development (cached copy)
 - `discovery: true` automatically discovers all endpoints from entity statement
 
+**Important**: Don't forget to configure CSRF protection (see [Step 7: Configure CSRF Protection](#step-7-configure-csrf-protection)) to ensure proper security for both request and callback phases.
+
 #### For OmniAuth (non-Rails)
 
 ```ruby
@@ -176,7 +178,11 @@ OmniauthOpenidFederation::FederationEndpoint.auto_configure(
 
 ```ruby
 # config/routes.rb
-OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+# RECOMMENDED: Mount the Engine (Rails-idiomatic way)
+mount OmniauthOpenidFederation::Engine => "/"
+
+# ALTERNATIVE: Use mount_routes helper (for backward compatibility)
+# OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
 ```
 
 **Key Points**:
@@ -186,34 +192,109 @@ OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
 
 ### Step 6: Add Routes
 
-#### For Devise
+#### Mount the Engine (Required for Federation Endpoints)
+
+The gem provides a Rails Engine that serves the well-known OpenID Federation endpoints. Mount it in your routes:
 
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
+  # Mount the Engine to enable /.well-known/openid-federation endpoint
+  mount OmniauthOpenidFederation::Engine => "/"
+  
+  # Your other routes...
   devise_for :users, controllers: {
     omniauth_callbacks: "users/omniauth_callbacks"
   }
 end
 ```
 
-#### For OmniAuth
+**Note**: The Engine is mounted at root (`"/"`) because OpenID Federation requires endpoints at specific well-known paths (e.g., `/.well-known/openid-federation`). The Engine's routes are defined in the gem and automatically available when mounted.
+
+#### For OmniAuth (Non-Devise)
 
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
+  mount OmniauthOpenidFederation::Engine => "/"
+  
   get "/auth/:provider/callback", to: "sessions#create"
   get "/auth/failure", to: "sessions#failure"
 end
 ```
 
-### Step 7: Create Callback Controller
+#### Alternative: Manual Route Mounting (Backward Compatibility)
+
+If you need custom paths or prefer manual route definition, you can use the `mount_routes` helper (deprecated):
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Use mount_routes helper for custom paths (deprecated - prefer Engine mounting)
+  OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+  # ... your other routes
+end
+```
+
+### Step 7: Configure CSRF Protection
+
+OmniAuth requires CSRF protection configuration to handle both the request phase (initiating OAuth) and callback phase (external provider redirect).
+
+**Important**: The request phase uses Rails CSRF tokens (forms must include them), while the callback phase uses OAuth state parameter for CSRF protection (external providers cannot include Rails CSRF tokens).
+
+#### For Devise (Rails)
+
+```ruby
+# config/initializers/devise.rb
+if defined?(OmniAuth)
+  OmniAuth.config.allowed_request_methods = [:post]
+  OmniAuth.config.silence_get_warning = false
+
+  # Configure CSRF validation to check tokens only for request phase (initiating OAuth)
+  # Callback phase uses OAuth state parameter for CSRF protection (validated in strategy)
+  # This ensures:
+  # - Request phase: Forms must include Rails CSRF tokens (standard Rails protection)
+  # - Callback phase: OAuth state parameter provides CSRF protection (external providers can't include Rails tokens)
+  OmniAuth.config.request_validation_phase = lambda do |env|
+    request = Rack::Request.new(env)
+    path = request.path
+
+    # Skip CSRF validation for callback paths (external providers can't include Rails CSRF tokens)
+    # OAuth state parameter provides CSRF protection for callbacks (validated in OpenIDFederation strategy)
+    return true if path.end_with?("/callback")
+
+    # For request phase, use Rails' standard CSRF token validation
+    # This ensures forms must include valid CSRF tokens when initiating OAuth
+    session = env["rack.session"] || {}
+    token = request.params["authenticity_token"] || request.get_header("X-CSRF-Token")
+    expected_token = session[:_csrf_token] || session["_csrf_token"]
+
+    # Validate CSRF token using constant-time comparison
+    if token.present? && expected_token.present?
+      ActiveSupport::SecurityUtils.secure_compare(token.to_s, expected_token.to_s)
+    else
+      false
+    end
+  end
+end
+```
+
+**Security Notes**:
+- **Request phase** (initiating OAuth): Forms must include Rails CSRF tokens via `button_to` or `form_with` helpers
+- **Callback phase** (external provider redirect): OAuth `state` parameter provides CSRF protection (automatically validated in `OpenIDFederation` strategy using constant-time comparison)
+- Both layers provide equivalent security - Rails CSRF tokens for request phase, OAuth state parameter for callbacks
+
+### Step 8: Create Callback Controller
 
 #### For Devise
 
 ```ruby
 # app/controllers/users/omniauth_callbacks_controller.rb
 class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  # Skip Rails CSRF protection for OAuth callbacks
+  # OAuth callbacks from external providers cannot include Rails CSRF tokens
+  # CSRF protection is handled by OAuth state parameter validation in the strategy
+  skip_before_action :verify_authenticity_token, only: [:openid_federation, :failure]
   skip_before_action :authenticate_user!, only: [:openid_federation, :failure]
 
   def openid_federation
@@ -233,7 +314,9 @@ class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
 end
 ```
 
-### Step 8: Create User Model Method
+**Note**: The `skip_before_action :verify_authenticity_token` is required because Rails' `protect_from_forgery` in `ApplicationController` checks CSRF tokens for all POST requests. External providers cannot include Rails CSRF tokens in callbacks, so we skip Rails' check while relying on OAuth state parameter validation (handled by the strategy).
+
+### Step 9: Create User Model Method
 
 ```ruby
 # app/models/user.rb
@@ -363,7 +446,8 @@ end
 ```
 
 **Instrumented Events**:
-- `csrf_detected` - CSRF attack detected (state mismatch)
+- `csrf_detected` - CSRF attack detected (state mismatch in callback phase)
+- `authenticity_error` - OmniAuth CSRF protection blocked request (Rails CSRF token validation failed in request phase)
 - `signature_verification_failed` - JWT signature verification failed (possible MITM)
 - `decryption_failed` - Token decryption failed (possible MITM or key mismatch)
 - `token_validation_failed` - Token validation failed (possible tampering)
@@ -372,9 +456,14 @@ end
 - `entity_statement_validation_failed` - Entity statement validation failed (possible MITM)
 - `fingerprint_mismatch` - Entity statement fingerprint mismatch (possible MITM)
 - `trust_chain_validation_failed` - Trust chain validation failed
-- `unexpected_authentication_break` - Unexpected authentication failure
+- `unexpected_authentication_break` - Unexpected authentication failure (missing code, token exchange errors, unknown errors)
 - `missing_required_claims` - Token missing required claims
 
+**Note**: All blocking exceptions are automatically reported through instrumentation, including:
+- OmniAuth middleware errors (like `AuthenticityTokenProtection` blocking requests)
+- Strategy-level errors (CSRF detected, missing code, token exchange failures)
+- Unknown error types (reported as `unexpected_authentication_break`)
+
 **Security Note**: All sensitive data (tokens, keys, fingerprints) is automatically sanitized before being sent to your instrumentation callback.
 
 **Key Rotation Types**:
@@ -521,7 +610,11 @@ OmniauthOpenidFederation::FederationEndpoint.auto_configure(
 
 ```ruby
 # config/routes.rb
-OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+# RECOMMENDED: Mount the Engine (Rails-idiomatic way)
+mount OmniauthOpenidFederation::Engine => "/"
+
+# ALTERNATIVE: Use mount_routes helper (for backward compatibility)
+# OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
 ```
 
 **What `auto_configure` does automatically**:
@@ -742,6 +835,13 @@ See inline code documentation for complete API reference.
 - Provider may have rotated keys (auto-handled with `rotate_on_errors: true`)
 - Clear cache: `Rails.cache.delete_matched("openid_federation_jwks_*")`
 
+**"Attack prevented by OmniAuth::AuthenticityTokenProtection" or "OmniAuth::AuthenticityError"**
+- **Request phase (initiating OAuth)**: Ensure forms include Rails CSRF tokens using `button_to` or `form_with` helpers
+- **Callback phase (external provider redirect)**: Ensure CSRF protection is configured correctly (see [Step 7: Configure CSRF Protection](#step-7-configure-csrf-protection))
+- Verify `OmniAuth.config.request_validation_phase` is configured to skip CSRF validation for callback paths
+- Ensure `skip_before_action :verify_authenticity_token` is present in the callback controller for callback actions
+- Check that OAuth state parameter validation is working (handled automatically by the strategy)
+
 ## Security
 
 See [SECURITY.md](SECURITY.md) for detailed security features, protections, and vulnerability reporting.

data/SECURITY.md

@@ -4,126 +4,25 @@
 
 **Do NOT** open a public GitHub issue for security vulnerabilities.
 
-Email security details to: **contact@kiskolabs.com**
+Email security details to: **security@kiskolabs.com**
 
 Include: description, steps to reproduce, potential impact, and suggested fix (if available).
 
-**Response Timeline:**
-- Acknowledgment within 48 hours
-- Initial assessment within 7 days
-- Coordinated disclosure after patching
+### Response Timeline
 
-## Library Security Features
+- We will acknowledge receipt of your report
+- We will provide an initial assessment
+- We will keep you informed of our progress and resolution timeline
 
-### Implemented Protections
+### Disclosure Policy
 
-**✅ Constant-Time State Comparison**
-- Uses `Rack::Utils.secure_compare` for state parameter validation to prevent timing attacks
-- Location: `strategy.rb:182`
-
-**✅ Path Traversal Protection**
-- `Utils.validate_file_path!` prevents `..` sequences and validates against allowed directories
-- File paths are restricted to configured allowed directories
-
-**✅ Signed Request Objects (RFC 9101)**
-- All authorization requests **MUST** use signed request objects (mandatory per OpenID Federation 1.0 spec)
-- Signing is enforced at library level - cannot be bypassed
-- Request objects **MAY** be encrypted (optional) when provider requires it or `always_encrypt_request_object` is enabled
-- Prevents parameter tampering and ensures request authenticity
-
-**✅ JWT Algorithm Validation**
-- JWT library validates algorithms and signatures
-- Unsigned tokens (`alg: none`) are explicitly handled and rejected for signed tokens
-- Only strong algorithms accepted (RS256, etc.)
-
-**✅ Logging Sanitization**
-- Sensitive data (tokens, keys) is never logged
-- File paths are sanitized before logging
-- URLs are sanitized (query parameters removed) in debug logs
-
-**✅ Timeout Limits**
-- HTTP requests have configurable timeouts to prevent long-running requests
-
-### Known Limitations & Risks
-
-**⚠️ SSRF Risk (Server-Side Request Forgery)**
-- The library fetches entity statements and JWKS from URLs without validating against internal network access
-- **Risk:** URLs could target localhost, private IPs, or cloud metadata endpoints
-- **Mitigation:** Application should validate URLs before passing to library, or implement URL validation in library configuration
-
-**⚠️ Memory Safety**
-- Ruby does not provide secure memory management for sensitive data
-- Private keys may persist in memory until garbage collection
-- Memory dumps may contain key material
-- **Mitigation:** Use secure environments and access controls
-
-**⚠️ SSL/TLS Verification**
-- SSL verification is automatically disabled in Rails development mode
-- **Production:** Application must ensure SSL verification is enabled
-
-**⚠️ Entity Statement Validation**
-- Fingerprint validation is optional - skipping validation may allow malicious entity statements
-- **Recommendation:** Always validate entity statement fingerprints when fetching from untrusted sources
-
-**⚠️ Key Rotation Window**
-- Brief window (up to cache TTL, default 24 hours) where rotated keys might not be immediately available
-- Library handles this with retry logic, but applications should monitor rotation events
-
-## Input/Output Points
-
-### Input Points (Library Handles)
-
-1. **OAuth Callback Parameters** (`code`, `state`, `error`)
-   - State validated with constant-time comparison
-   - Authorization codes are single-use and time-limited
-
-2. **OAuth Request Parameters** (`acr_values`, `login_hint`, etc.)
-   - All parameters are signed in JWT request objects (RFC 9101)
-   - Parameters validated before inclusion
-
-3. **Entity Statement URLs**
-   - Fetched via HTTP client
-   - **SSRF Risk:** No validation against internal network access
-
-4. **File Paths** (configuration)
-   - Validated with `Utils.validate_file_path!` to prevent path traversal
-   - Restricted to allowed directories
-
-5. **JWT/JWE Tokens** (from OAuth provider)
-   - Algorithm validation enforced
-   - Signature validation required for signed tokens
-   - Entity statement fingerprints provide additional validation
-
-### Output Points (Library Exposes)
-
-1. **HTTP Responses** (if using `RackEndpoint`)
-   - `/.well-known/openid-federation` - Entity statement (JWT)
-   - `/.well-known/jwks.json` - Public JWKS
-   - `/.well-known/signed-jwks.json` - Signed JWKS (JWT)
-   - Only public keys exposed (private keys never exposed)
-
-2. **Logs**
-   - Sensitive data (tokens, keys) never logged
-   - File paths and URLs sanitized before logging
-
-3. **Error Messages**
-   - File paths sanitized in error messages
-   - Generic error messages (stack traces only in development)
-
-## Security Considerations
-
-- **Timing Attacks**: State parameter protected with constant-time comparison
-- **Path Traversal**: ✅ `Utils.validate_file_path!` prevents `..` sequences
-- **JWT Algorithm Confusion**: ✅ Algorithm validation enforced, `alg: none` rejected
-- **Replay Attacks**: Authorization codes are single-use and time-limited
+- We will work with you to understand and resolve the issue
+- We will credit you for the discovery (unless you prefer to remain anonymous)
+- We will publish a security advisory after the vulnerability is patched
+- We will coordinate public disclosure with you
 
 ## Automation Security
 
 * **Context Isolation:** It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
 
 * **Supply Chain:** All automated dependencies must be verified.
-
-## Contact
-
-**Security concerns**: contact@kiskolabs.com  
-**General support**: https://github.com/amkisko/omniauth_openid_federation.rb/issues

data/examples/app/controllers/users/omniauth_callbacks_controller.rb.example

@@ -2,6 +2,10 @@
 # Copy this to app/controllers/users/omniauth_callbacks_controller.rb
 
 class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  # Skip Rails CSRF protection for OAuth callbacks
+  # OAuth callbacks from external providers cannot include Rails CSRF tokens
+  # CSRF protection is handled by OAuth state parameter validation in the strategy
+  skip_before_action :verify_authenticity_token, only: [:openid_federation, :failure]
   skip_before_action :authenticate_user!, only: [:openid_federation, :failure]
 
   def openid_federation

data/examples/config/initializers/devise.rb.example

@@ -72,6 +72,40 @@ OmniauthOpenidFederation::EndpointResolver.validate_and_build_audience(
 Devise.setup do |config|
   # ... your other Devise configuration ...
 
+  # OmniAuth 2.0+ defaults to POST only for CSRF protection (CVE-2015-9284)
+  # Always use POST for security - forms must include CSRF token
+  if defined?(OmniAuth)
+    OmniAuth.config.allowed_request_methods = [:post]
+    OmniAuth.config.silence_get_warning = false
+
+    # Configure CSRF validation to check tokens only for request phase (initiating OAuth)
+    # Callback phase uses OAuth state parameter for CSRF protection (validated in strategy)
+    # This ensures:
+    # - Request phase: Forms must include Rails CSRF tokens (standard Rails protection)
+    # - Callback phase: OAuth state parameter provides CSRF protection (external providers can't include Rails tokens)
+    OmniAuth.config.request_validation_phase = lambda do |env|
+      request = Rack::Request.new(env)
+      path = request.path
+
+      # Skip CSRF validation for callback paths (external providers can't include Rails CSRF tokens)
+      # OAuth state parameter provides CSRF protection for callbacks (validated in OpenIDFederation strategy)
+      return true if path.end_with?("/callback")
+
+      # For request phase, use Rails' standard CSRF token validation
+      # This ensures forms must include valid CSRF tokens when initiating OAuth
+      session = env["rack.session"] || {}
+      token = request.params["authenticity_token"] || request.get_header("X-CSRF-Token")
+      expected_token = session[:_csrf_token] || session["_csrf_token"]
+
+      # Validate CSRF token using constant-time comparison
+      if token.present? && expected_token.present?
+        ActiveSupport::SecurityUtils.secure_compare(token.to_s, expected_token.to_s)
+      else
+        false
+      end
+    end
+  end
+
   config.omniauth :openid_federation,
     name: :openid_federation,
     scope: [:openid],

data/lib/omniauth_openid_federation/engine.rb

@@ -0,0 +1,21 @@
+# Rails Engine for OpenID Federation endpoints
+# Provides controllers and routes for well-known OpenID Federation endpoints
+#
+# @see https://guides.rubyonrails.org/engines.html Rails Engines Guide
+module OmniauthOpenidFederation
+  class Engine < ::Rails::Engine
+    # Don't isolate namespace because we need routes at specific well-known paths
+    # (/.well-known/openid-federation) rather than under a mount point
+    # isolate_namespace OmniauthOpenidFederation
+
+    # Explicitly require the controller to avoid Zeitwerk conflicts
+    # For local path gems, autoload_once_paths can cause conflicts with main app's loader
+    # We require the controller explicitly in to_prepare to ensure it's available for routing
+    config.to_prepare do
+      # Use self.class to access Engine class methods (root is a class method)
+      engine_root = OmniauthOpenidFederation::Engine.root
+      controller_path = engine_root.join("app", "controllers", "omniauth_openid_federation", "federation_controller.rb")
+      require controller_path.to_s if controller_path.exist?
+    end
+  end
+end

data/lib/omniauth_openid_federation/entity_statement_reader.rb

@@ -115,6 +115,13 @@ module OmniauthOpenidFederation
           # Log security error but return nil to maintain backward compatibility
           Logger.warn("[EntityStatementReader] Security error: #{e.message}")
           nil
+        rescue Errno::EACCES, Errno::EISDIR, Errno::ENOENT
+          # Handle file system errors gracefully to avoid exposing file system structure
+          # EACCES: Permission denied
+          # EISDIR: Is a directory
+          # ENOENT: No such file or directory (race condition after File.exist?)
+          Logger.warn("[EntityStatementReader] File access error: #{Utils.sanitize_path(entity_statement_path)}")
+          nil
         end
       end
     end

data/lib/omniauth_openid_federation/federation/entity_statement_validator.rb

@@ -393,8 +393,8 @@ module OmniauthOpenidFederation
         if unknown_claims.any?
           # For now, we'll log a warning but not reject
           # In a strict implementation, we should reject if we don't understand the claims
+          # Future enhancement: Add strict_mode option to reject unknown crit claims
           OmniauthOpenidFederation::Logger.warn("[EntityStatementValidator] Entity statement contains crit claim with unknown claims: #{unknown_claims.join(", ")}. These claims MUST be understood and processed.")
-          # TODO: Make this configurable - strict mode should reject unknown crit claims
         end
       end
 

data/lib/omniauth_openid_federation/federation_endpoint.rb

@@ -547,22 +547,21 @@ module OmniauthOpenidFederation
 
       # Mount the federation endpoint routes in Rails routes
       #
-      # Add this to your config/routes.rb:
+      # RECOMMENDED: Use the Engine (Rails-idiomatic way):
       #   Rails.application.routes.draw do
-      #     OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+      #     mount OmniauthOpenidFederation::Engine => "/"
       #   end
       #
-      # This mounts all four endpoints:
+      # This mounts all four endpoints at the root level:
       #   - GET /.well-known/openid-federation (entity statement)
       #   - GET /.well-known/openid-federation/fetch (fetch endpoint for Subordinate Statements)
       #   - GET /.well-known/jwks.json (standard JWKS)
       #   - GET /.well-known/signed-jwks.json (signed JWKS)
       #
-      # Or manually:
-      #   get "/.well-known/openid-federation", to: "omniauth_openid_federation/federation#show"
-      #   get "/.well-known/openid-federation/fetch", to: "omniauth_openid_federation/federation#fetch"
-      #   get "/.well-known/jwks.json", to: "omniauth_openid_federation/federation#jwks"
-      #   get "/.well-known/signed-jwks.json", to: "omniauth_openid_federation/federation#signed_jwks"
+      # ALTERNATIVE: Use mount_routes helper (for backward compatibility or custom paths):
+      #   Rails.application.routes.draw do
+      #     OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+      #   end
       #
       # @param router [ActionDispatch::Routing::Mapper] The routes mapper (pass `self` from routes.rb)
       # @param entity_statement_path [String] Path for entity statement endpoint (default: "/.well-known/openid-federation")
@@ -570,6 +569,7 @@ module OmniauthOpenidFederation
       # @param jwks_path [String] Path for standard JWKS endpoint (default: "/.well-known/jwks.json")
       # @param signed_jwks_path [String] Path for signed JWKS endpoint (default: "/.well-known/signed-jwks.json")
       # @param as [String, Symbol] Route name prefix (default: :openid_federation)
+      # @deprecated Use `mount OmniauthOpenidFederation::Engine => "/"` instead (Rails-idiomatic way)
       def mount_routes(router, entity_statement_path: "/.well-known/openid-federation", fetch_path: "/.well-known/openid-federation/fetch", jwks_path: "/.well-known/jwks.json", signed_jwks_path: "/.well-known/signed-jwks.json", as: :openid_federation)
         # Controller uses Rails-conventional naming (OmniauthOpenidFederation)
         # which matches natural inflection from omniauth_openid_federation

data/lib/omniauth_openid_federation/instrumentation.rb

@@ -46,6 +46,7 @@ module OmniauthOpenidFederation
     EVENT_ISSUER_MISMATCH = "issuer_mismatch"
     EVENT_EXPIRED_TOKEN = "expired_token"
     EVENT_INVALID_NONCE = "invalid_nonce"
+    EVENT_AUTHENTICITY_ERROR = "authenticity_error"
 
     class << self
       # Notify about a security event
@@ -348,6 +349,21 @@ module OmniauthOpenidFederation
         )
       end
 
+      # Notify about authenticity token error (OmniAuth CSRF protection)
+      #
+      # @param data [Hash] Additional context (error_type, error_message, phase, request_info)
+      # @return [void]
+      def notify_authenticity_error(data = {})
+        notify(
+          EVENT_AUTHENTICITY_ERROR,
+          data: {
+            reason: "OmniAuth authenticity token validation failed - CSRF protection blocked request",
+            **data
+          },
+          severity: :error
+        )
+      end
+
       private
 
       # Sanitize data to remove sensitive information

data/lib/omniauth_openid_federation/jwks/decode.rb

@@ -165,8 +165,9 @@ module OmniauthOpenidFederation
       # @return [Array<Hash>] Array with [payload, header]
       # @raise [ValidationError] If JWT validation fails
       # @raise [SignatureError] If signature verification fails
-      # @deprecated Use jwt() method instead
+      # @deprecated Use jwt() method instead. This method will be removed in a future version.
       def self.json_jwt(encoded_jwt, jwks_uri, retried: false, entity_statement_keys: nil)
+        OmniauthOpenidFederation::Logger.warn("[Jwks::Decode] json_jwt is deprecated. Use jwt() method instead.")
         jwt(encoded_jwt, jwks_uri, retried: retried, entity_statement_keys: entity_statement_keys)
       end
     end

data/lib/omniauth_openid_federation/jws.rb

@@ -65,7 +65,7 @@ module OmniauthOpenidFederation
     attr_accessor :private_key, :state, :nonce
     # Provider-specific extension parameters (outside JWT)
     # Some providers may require additional parameters that are not part of the JWT
-    # @deprecated Use provider_extension_params hash instead
+    # @deprecated Use request_object_params option in strategy instead (adds params to the JWT request object)
     attr_accessor :ftn_spname
 
     # Initialize JWT request object builder
@@ -256,12 +256,6 @@ module OmniauthOpenidFederation
       JWT.encode(claim, @private_key, "RS256", header)
     end
 
-    def load_signing_key
-      # Deprecated: Use KeyExtractor.extract_signing_key instead
-      # This method is kept for backward compatibility but should not be used
-      nil
-    end
-
     def signing_key_kid
       metadata = load_metadata_from_entity_statement
       return nil unless metadata

data/lib/omniauth_openid_federation/railtie.rb

@@ -1,26 +1,12 @@
-# Railtie to load rake tasks and provide Rails integration
+# Railtie to load rake tasks
+# Note: Controllers and routes are now handled by the Engine (lib/omniauth_openid_federation/engine.rb)
+# This Railtie is kept for backward compatibility and for loading rake tasks
 if defined?(Rails)
   module OmniauthOpenidFederation
     class Railtie < Rails::Railtie
-      # Add gem's controllers to autoload paths
-      # This ensures the controller can be found by Rails routing
-      initializer "omniauth_openid_federation.add_autoload_paths", before: :set_autoload_paths do |app|
-        controllers_path = File.join(File.dirname(__FILE__), "..", "..", "app", "controllers")
-        app.config.autoload_once_paths << controllers_path if File.exist?(controllers_path)
-      end
-
-      # Load controller when Rails is available (for development reloading)
-      config.to_prepare do
-        controller_path = File.join(File.dirname(__FILE__), "..", "..", "app", "controllers", "omniauth_openid_federation", "federation_controller.rb")
-        require controller_path if File.exist?(controller_path)
-      end
-
       rake_tasks do
         # Load rake tasks from lib/tasks
         # Rails automatically loads lib/tasks/**/*.rake, but we ensure they're loaded here too
-        # File.dirname(__FILE__) = lib/omniauth_openid_federation
-        # .. = lib
-        # tasks = lib/tasks
         task_files = Dir[File.join(File.dirname(__FILE__), "..", "tasks", "**", "*.rake")]
         task_files.each { |task_file| load task_file } if task_files.any?
       end

data/lib/omniauth_openid_federation/strategy.rb

@@ -186,6 +186,83 @@ module OmniAuth
         client
       end
 
+      # Override fail! to instrument all authentication failures
+      # This catches failures from OmniAuth middleware (like AuthenticityTokenProtection)
+      # as well as failures from within the strategy
+      #
+      # @param error_type [Symbol] Error type identifier
+      # @param exception [Exception] Exception object
+      # @return [void]
+      def fail!(error_type, exception = nil)
+        # Determine if this error has already been instrumented
+        # Errors instrumented before calling fail! will have a flag set
+        already_instrumented = env["omniauth_openid_federation.instrumented"] == true
+
+        unless already_instrumented
+          # Extract error information
+          error_message = exception&.message || error_type.to_s
+          error_class = exception&.class&.name || "UnknownError"
+
+          # Determine the phase (request or callback)
+          phase = request.path.end_with?("/callback") ? "callback_phase" : "request_phase"
+
+          # Build request info
+          request_info = {
+            remote_ip: request.env["REMOTE_ADDR"],
+            user_agent: request.env["HTTP_USER_AGENT"],
+            path: request.path,
+            method: request.request_method
+          }
+
+          # Instrument based on error type
+          case error_type.to_sym
+          when :authenticity_error
+            # OmniAuth CSRF protection error (from middleware)
+            OmniauthOpenidFederation::Instrumentation.notify_authenticity_error(
+              error_type: error_type.to_s,
+              error_message: error_message,
+              error_class: error_class,
+              phase: phase,
+              request_info: request_info
+            )
+          when :csrf_detected
+            # This should already be instrumented before calling fail!, but instrument here as fallback
+            # (e.g., if fail! is called directly without prior instrumentation)
+            OmniauthOpenidFederation::Instrumentation.notify_csrf_detected(
+              error_type: error_type.to_s,
+              error_message: error_message,
+              phase: phase,
+              request_info: request_info
+            )
+          when :missing_code, :token_exchange_error
+            # These should already be instrumented before calling fail!, but instrument here as fallback
+            # (e.g., if fail! is called directly without prior instrumentation)
+            OmniauthOpenidFederation::Instrumentation.notify_unexpected_authentication_break(
+              stage: phase,
+              error_message: error_message,
+              error_class: error_class,
+              error_type: error_type.to_s,
+              request_info: request_info
+            )
+          else
+            # Unknown error type - instrument as unexpected authentication break
+            OmniauthOpenidFederation::Instrumentation.notify_unexpected_authentication_break(
+              stage: phase,
+              error_message: error_message,
+              error_class: error_class,
+              error_type: error_type.to_s,
+              request_info: request_info
+            )
+          end
+        end
+
+        # Mark as instrumented to prevent double instrumentation
+        env["omniauth_openid_federation.instrumented"] = true
+
+        # Call parent fail! method
+        super
+      end
+
       # Override request_phase to use our custom authorize_uri instead of client.auth_code
       # The base OAuth2 strategy calls client.auth_code.authorize_url, but OpenIDConnect::Client
       # doesn't have an auth_code method - it uses authorization_uri directly
@@ -218,6 +295,8 @@ module OmniAuth
               path: request.path
             }
           )
+          # Mark as instrumented to prevent double instrumentation in fail!
+          env["omniauth_openid_federation.instrumented"] = true
           fail!(:csrf_detected, OmniauthOpenidFederation::SecurityError.new("CSRF detected"))
           return
         end
@@ -238,6 +317,8 @@ module OmniAuth
               path: request.path
             }
           )
+          # Mark as instrumented to prevent double instrumentation in fail!
+          env["omniauth_openid_federation.instrumented"] = true
           fail!(:missing_code, OmniauthOpenidFederation::ValidationError.new("Missing authorization code"))
           return
         end
@@ -258,6 +339,8 @@ module OmniAuth
               path: request.path
             }
           )
+          # Mark as instrumented to prevent double instrumentation in fail!
+          env["omniauth_openid_federation.instrumented"] = true
           fail!(:token_exchange_error, e)
           return
         end
@@ -419,13 +502,15 @@ module OmniAuth
 
         # Add provider-specific extension parameters if configured
         # Note: Some providers may require additional parameters outside the JWT
-        # The deprecated ftn_spname option is supported for backward compatibility
+        # @deprecated ftn_spname option - Use request_object_params instead for adding params to the JWT request object
         if options.ftn_spname && !options.ftn_spname.to_s.empty?
+          OmniauthOpenidFederation::Logger.warn("[Strategy] ftn_spname option is deprecated. Use request_object_params: ['ftn_spname'] instead.")
           jws_builder.ftn_spname = options.ftn_spname
         end
 
-        # Allow dynamic authorize params if configured
-        options.allow_authorize_params&.each do |key|
+        # Allow dynamic request object params from HTTP request if configured
+        # These parameters are added as claims to the JWT request object (RFC 9101)
+        options.request_object_params&.each do |key|
           value = request_params[key.to_s]
           jws_builder.add_claim(key.to_sym, value) if value && !value.to_s.empty?
         end
@@ -470,7 +555,7 @@ module OmniAuth
 
         # Add provider-specific extension parameters outside JWT if configured
         # These are allowed per provider requirements (some providers require additional parameters)
-        # The deprecated ftn_spname option is supported for backward compatibility
+        # @deprecated ftn_spname option - Use request_object_params instead for adding params to the JWT request object
         if options.ftn_spname && !options.ftn_spname.to_s.empty?
           query_params[:ftn_spname] = options.ftn_spname
         end

data/lib/omniauth_openid_federation/utils.rb

@@ -83,6 +83,8 @@ module OmniauthOpenidFederation
       resolved = File.expand_path(path_str)
 
       # Validate it's within allowed directories if specified
+      # When allowed_dirs is nil, we trust the developer to pass appropriate paths
+      # Path traversal protection (.. and ~) is still enforced above
       if allowed_dirs && !allowed_dirs.empty?
         allowed = allowed_dirs.any? do |dir|
           expanded_dir = File.expand_path(dir)

data/lib/omniauth_openid_federation/version.rb

@@ -1,3 +1,3 @@
 module OmniauthOpenidFederation
-  VERSION = "1.0.0".freeze
+  VERSION = "1.2.0".freeze
 end

data/lib/omniauth_openid_federation.rb

@@ -82,8 +82,9 @@ module OmniauthOpenidFederation
   end
 end
 
-# Load Railtie for Rails integration (rake tasks, etc.)
+# Load Engine for Rails integration (controllers, routes, etc.)
 if defined?(Rails)
+  require_relative "omniauth_openid_federation/engine"
   require_relative "omniauth_openid_federation/railtie"
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth_openid_federation
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -83,16 +83,22 @@ dependencies:
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -285,6 +291,7 @@ files:
 - lib/omniauth_openid_federation/configuration.rb
 - lib/omniauth_openid_federation/constants.rb
 - lib/omniauth_openid_federation/endpoint_resolver.rb
+- lib/omniauth_openid_federation/engine.rb
 - lib/omniauth_openid_federation/entity_statement_reader.rb
 - lib/omniauth_openid_federation/errors.rb
 - lib/omniauth_openid_federation/federation/entity_statement.rb