omniauth_openid_federation 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff53053ffcbf2f63f91ae342158b5f11e881f3466c8d1ec1a25c06c8d1ff6b9b
-  data.tar.gz: d11bdc15e0dbbbd710cee19ac670a7425af0f3e37e42765c93df9d4dfac224ac
+  metadata.gz: d1df7531d0ec2cac4095580f068c1dc7cb09fe53631d87a647b311c05ee9c89f
+  data.tar.gz: 38f06cb5ca370edd986051c4f547b0e53d07d1a61c685cb727c6f2d0e2b34c46
 SHA512:
-  metadata.gz: '082caf05aaf09898c6bd992f9280570dec07ad19acedf59dcfbf8c60e74af84f03e9f140eab5d4fe4156e97d418bf5c77d623026923d4f748889cc18e555101d'
-  data.tar.gz: 27db7564021a934505269f60bb08eb1eba84eb763b9ea5fd6c06815e4e92cd72cbefed49779d15b9bb872c729525ec3ae3760204ce1948673e708a3ae0e1f655
+  metadata.gz: 81261964b6f0fd468dde2e70b0331e2435129896114b7d4cd087a366596906f160fac90296f856c9055d15e49e51cd8dd8a5ad83d8234b2bec264c49b625b789
+  data.tar.gz: a9d48264edb247c18ce0160fa339f429c3802033e902da6b7c1ef12de5892c44c392415c8ffd57ac6b976190d85a071a199ad3790cc97f0cfe1d4c164d35acba

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## 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
@@ -207,13 +209,65 @@ Rails.application.routes.draw do
 end
 ```
 
-### Step 7: Create Callback Controller
+### 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 +287,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 +419,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 +429,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**:
@@ -742,6 +804,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/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/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/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.1.0".freeze
 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.1.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