omniauth_openid_federation 1.0.0

data/lib/omniauth_openid_federation/jwks/decode.rb

@@ -0,0 +1,174 @@
+require "jwt"
+require "digest"
+require "base64"
+require_relative "../logger"
+require_relative "../errors"
+require_relative "../cache"
+require_relative "fetch"
+
+# JWT decoding service with automatic key rotation handling
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+# @see https://openid.net/specs/openid-federation-1_0.html#section-11.1 Section 11.1: Protocol Key Rollover
+#
+# Decodes and validates JWTs using JWKS from the provider. Implements automatic
+# key rotation handling by:
+# - Detecting signature verification failures (possible key rotation)
+# - Clearing JWKS cache and re-fetching fresh keys
+# - Retrying JWT validation with updated keys
+#
+# This handles provider key rotation automatically without manual intervention.
+# Providers will notify before key rotation, and this implementation handles it gracefully.
+module OmniauthOpenidFederation
+  module Jwks
+    class Decode
+      # Decode JWT with automatic key rotation handling
+      #
+      # @param encoded_jwt [String] The JWT to decode
+      # @param jwks_uri [String] The JWKS URI for key lookup
+      # @param retried [Boolean] Internal flag for retry logic (default: false)
+      # @param entity_statement_keys [Hash, Array, nil] Entity statement keys for validation
+      # @yield [jwks] Optional block to process JWKS before decoding
+      # @yieldparam jwks [Hash] The JWKS hash
+      # @return [Object] Result from block or JWKS hash
+      # @raise [ValidationError] If JWT validation fails
+      # @raise [SignatureError] If signature verification fails after retry
+      def self.run(encoded_jwt, jwks_uri, retried: false, entity_statement_keys: nil, &block)
+        # Fetch JWKS
+        jwks = OmniauthOpenidFederation::Jwks::Fetch.run(jwks_uri, entity_statement_keys: entity_statement_keys)
+
+        begin
+          # Try to decode
+          if block_given?
+            yield(jwks)
+          else
+            jwks
+          end
+        rescue JWT::ExpiredSignature, JWT::InvalidJtiError, JWT::InvalidIatError, JWT::InvalidAudError, JWT::InvalidIssuerError => e
+          # These are JWT validation errors that shouldn't trigger retry
+          # They indicate the token itself is invalid (expired, wrong audience, etc.), not that the keys are wrong
+          OmniauthOpenidFederation::Logger.error("[Jwks::Decode] JWT validation failed: #{e.class} - #{e.message}")
+          raise ValidationError, e.message, e.backtrace
+        rescue JWT::DecodeError => e
+          # JWT::DecodeError can be either:
+          # - Format errors (invalid JWT structure) - shouldn't retry
+          # - Verification errors (signature mismatch) - should retry (might be key rotation)
+          # - Key not found errors (kid not found) - should raise ValidationError
+          if e.message.include?("Could not find public key for kid") || e.message.include?("Key with kid")
+            # Key not found error - might indicate key rotation, so clear cache and retry once
+            if retried
+              # Already retried, raise ValidationError
+              error_msg = "Key with kid not found in JWKS after cache refresh: #{e.message}"
+              OmniauthOpenidFederation::Logger.error("[Jwks::Decode] #{error_msg}")
+              raise ValidationError, error_msg, e.backtrace
+            else
+              # First attempt - clear cache and retry (might be key rotation)
+              OmniauthOpenidFederation::Logger.warn("[Jwks::Decode] Key with kid not found (clearing cache and retrying - possible key rotation): #{e.message}")
+              # Instrument key rotation detection
+              OmniauthOpenidFederation::Instrumentation.notify_key_rotation_detected(
+                jwks_uri: jwks_uri,
+                error_message: e.message,
+                error_class: e.class.name,
+                reason: "kid_not_found"
+              )
+              OmniauthOpenidFederation::Cache.delete_jwks(jwks_uri)
+              run(encoded_jwt, jwks_uri, retried: true, entity_statement_keys: entity_statement_keys, &block)
+            end
+          elsif e.is_a?(JWT::VerificationError) || e.message.include?("verification") || e.message.include?("signature")
+            # Verification error - might be key rotation, so retry
+            if retried
+              error_msg = "JWT signature verification failed after cache refresh (possible key rotation issue): #{e.class} - #{e.message}"
+              OmniauthOpenidFederation::Logger.error("[Jwks::Decode] #{error_msg}")
+              # Instrument signature verification failure after retry
+              OmniauthOpenidFederation::Instrumentation.notify_signature_verification_failed(
+                token_type: "jwt",
+                jwks_uri: jwks_uri,
+                error_message: e.message,
+                error_class: e.class.name,
+                retried: true
+              )
+              raise SignatureError, error_msg, e.backtrace
+            else
+              OmniauthOpenidFederation::Logger.warn("[Jwks::Decode] JWT signature verification failed (clearing cache and retrying - possible key rotation): #{e.class} - #{e.message}")
+              # Instrument key rotation detection
+              OmniauthOpenidFederation::Instrumentation.notify_key_rotation_detected(
+                jwks_uri: jwks_uri,
+                error_message: e.message,
+                error_class: e.class.name
+              )
+              OmniauthOpenidFederation::Cache.delete_jwks(jwks_uri)
+              run(encoded_jwt, jwks_uri, retried: true, entity_statement_keys: entity_statement_keys, &block)
+            end
+          else
+            # Format error - don't retry
+            error_msg = "JWT format error: #{e.class} - #{e.message}"
+            OmniauthOpenidFederation::Logger.error("[Jwks::Decode] #{error_msg}")
+            raise ValidationError, error_msg, e.backtrace
+          end
+        rescue ArgumentError => e
+          # Argument errors from invalid JWT format
+          if e.message.include?("Invalid")
+            error_msg = "JWT decode failed due to invalid format: #{e.class} - #{e.message}"
+            OmniauthOpenidFederation::Logger.error("[Jwks::Decode] #{error_msg}")
+            raise ValidationError, error_msg, e.backtrace
+          else
+            raise e
+          end
+        rescue => e
+          # Other errors might be due to key rotation
+          if retried
+            # If already re-tried to fetch, raise error
+            error_msg = "JWT decode failed after cache refresh: #{e.class} - #{e.message}"
+            OmniauthOpenidFederation::Logger.error("[Jwks::Decode] #{error_msg}")
+            raise ValidationError, error_msg, e.backtrace
+          else
+            OmniauthOpenidFederation::Logger.warn("[Jwks::Decode] JWT decode error (clearing cache and retrying - possible key rotation): #{e.class} - #{e.message}")
+            # Reset cache to force re-fetching of keys
+            OmniauthOpenidFederation::Cache.delete_jwks(jwks_uri)
+            run(encoded_jwt, jwks_uri, retried: true, entity_statement_keys: entity_statement_keys, &block)
+          end
+        end
+      end
+
+      # Decode JWT using JWT gem
+      #
+      # @param encoded_jwt [String] The JWT to decode
+      # @param jwks_uri [String] The JWKS URI for key lookup
+      # @param retried [Boolean] Internal flag for retry logic (default: false)
+      # @param entity_statement_keys [Hash, Array, nil] Entity statement keys for validation
+      # @return [Array<Hash>] Array with [payload, header]
+      # @raise [ValidationError] If JWT validation fails
+      # @raise [SignatureError] If signature verification fails
+      def self.jwt(encoded_jwt, jwks_uri, retried: false, entity_statement_keys: nil)
+        run(encoded_jwt, jwks_uri, retried: retried, entity_statement_keys: entity_statement_keys) do |jwks|
+          # jwks should be a HashWithIndifferentAccess with "keys" array
+          jwks_for_decode = if jwks.is_a?(Hash) && jwks.key?("keys")
+            jwks
+          else
+            {keys: jwks}
+          end
+
+          ::JWT.decode(
+            encoded_jwt,
+            nil,
+            true,
+            {algorithms: ["RS256"], jwks: jwks_for_decode}
+          )
+        end
+      end
+
+      # Decode JWT using jwt gem (legacy method name kept for backward compatibility)
+      #
+      # @param encoded_jwt [String] The JWT to decode
+      # @param jwks_uri [String] The JWKS URI for key lookup
+      # @param retried [Boolean] Internal flag for retry logic (default: false)
+      # @param entity_statement_keys [Hash, Array, nil] Entity statement keys for validation
+      # @return [Array<Hash>] Array with [payload, header]
+      # @raise [ValidationError] If JWT validation fails
+      # @raise [SignatureError] If signature verification fails
+      # @deprecated Use jwt() method instead
+      def self.json_jwt(encoded_jwt, jwks_uri, retried: false, entity_statement_keys: nil)
+        jwt(encoded_jwt, jwks_uri, retried: retried, entity_statement_keys: entity_statement_keys)
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/jwks/fetch.rb

@@ -0,0 +1,153 @@
+require "http"
+require "jwt"
+require "openssl"
+require_relative "../logger"
+require_relative "../errors"
+require_relative "../http_client"
+require_relative "../cache"
+require_relative "../cache_adapter"
+require_relative "../utils"
+require_relative "../constants"
+require_relative "../rate_limiter"
+require_relative "normalizer"
+
+# JWKS fetching service with support for both standard and signed JWKS
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+# @see https://openid.net/specs/openid-federation-1_0.html#section-5.2.1.1 Section 5.2.1.1: Usage of jwks, jwks_uri, and signed_jwks_uri
+#
+# Fetches JWKS from either:
+# - Standard JWKS endpoint (jwks_uri) - Returns JSON directly
+# - Signed JWKS endpoint (signed_jwks_uri) - Returns a JWT containing JWKS, validated using entity statement keys
+#
+# Supports caching for performance (24 hour TTL by default) and handles both federation and standard OIDC scenarios.
+# According to RFC 7517 and OpenID Connect best practices, JWKS should be cached to reduce latency and avoid
+# unnecessary network requests. The cache TTL balances performance with key rotation needs.
+#
+# Key rotation is handled automatically via retry logic in Jwks::Decode which clears the cache
+# on signature verification failures, allowing fresh keys to be fetched when providers rotate keys.
+module OmniauthOpenidFederation
+  module Jwks
+    class Fetch
+      # Fetch JWKS from provider with caching support
+      #
+      # @param jwks_uri [String] The JWKS URI to fetch from
+      # @param entity_statement_keys [Hash, Array, nil] Entity statement keys for validating signed JWKS
+      # @param cache_ttl [Integer, nil] Cache TTL in seconds (default: from configuration)
+      #   - nil: Use configuration default (manual rotation if not set, or configured TTL)
+      #   - positive integer: Cache expires after this many seconds
+      # @param force_refresh [Boolean] Force refresh even if cached (default: false)
+      # @return [Hash] JWKS hash with "keys" array
+      # @raise [FetchError] If fetching fails
+      def self.run(jwks_uri, entity_statement_keys: nil, cache_ttl: nil, force_refresh: false)
+        cache_key = OmniauthOpenidFederation::Cache.key_for_jwks(jwks_uri)
+        config = OmniauthOpenidFederation::Configuration.config
+        cache_ttl ||= config.cache_ttl
+        rotate_on_errors = config.rotate_on_errors
+
+        # Use cache adapter if available, otherwise fetch directly
+        if CacheAdapter.available?
+          if force_refresh
+            # Force refresh: clear cache and fetch fresh
+            CacheAdapter.delete(cache_key)
+          end
+
+          if cache_ttl.nil?
+            # Manual rotation: cache forever, only rotate on errors if rotate_on_errors is enabled
+            begin
+              CacheAdapter.fetch(cache_key, expires_in: nil) do
+                fetch_jwks(jwks_uri, entity_statement_keys)
+              end
+            rescue KeyRelatedError => e
+              # Rotate on key-related errors if configured
+              if rotate_on_errors
+                OmniauthOpenidFederation::Logger.warn("[Jwks::Fetch] Key-related error detected, rotating cache: #{e.message}")
+                CacheAdapter.delete(cache_key)
+                fetch_jwks(jwks_uri, entity_statement_keys)
+              else
+                raise
+              end
+            end
+          else
+            # TTL-based cache: expires after cache_ttl seconds
+            # Rotate on errors if configured
+            begin
+              CacheAdapter.fetch(cache_key, expires_in: cache_ttl) do
+                fetch_jwks(jwks_uri, entity_statement_keys)
+              end
+            rescue KeyRelatedError => e
+              # Rotate on key-related errors if configured
+              if rotate_on_errors
+                OmniauthOpenidFederation::Logger.warn("[Jwks::Fetch] Key-related error detected, rotating cache: #{e.message}")
+                CacheAdapter.delete(cache_key)
+                fetch_jwks(jwks_uri, entity_statement_keys)
+              else
+                raise
+              end
+            end
+          end
+        else
+          fetch_jwks(jwks_uri, entity_statement_keys)
+        end
+      end
+
+      def self.fetch_jwks(jwks_uri, entity_statement_keys)
+        # Rate limiting to prevent DoS
+        unless RateLimiter.allow?(jwks_uri)
+          raise FetchError, "Rate limit exceeded for JWKS fetching"
+        end
+
+        # Use HTTP client with retry logic and configurable SSL verification
+        begin
+          response = HttpClient.get(jwks_uri)
+        rescue OmniauthOpenidFederation::NetworkError => e
+          sanitized_uri = Utils.sanitize_uri(jwks_uri)
+          OmniauthOpenidFederation::Logger.error("[Jwks::Fetch] Failed to fetch JWKS from #{sanitized_uri}: #{e.message}")
+          raise FetchError, "Failed to fetch JWKS: #{e.message}", e.backtrace
+        end
+
+        unless response.status.success?
+          sanitized_uri = Utils.sanitize_uri(jwks_uri)
+          error_msg = "Failed to fetch JWKS: HTTP #{response.status}"
+          OmniauthOpenidFederation::Logger.error("[Jwks::Fetch] #{error_msg} from #{sanitized_uri}")
+          # If it's a key-related error (401, 403, 404), this might indicate key rotation
+          if Constants::KEY_ROTATION_HTTP_CODES.include?(response.status.code)
+            raise KeyRelatedError, error_msg
+          else
+            raise FetchError, error_msg
+          end
+        end
+
+        if entity_statement_keys
+          # Validate signed JWKS using entity statement keys
+          # If jwks_uri returns a JWT (signed JWKS), validate it
+          if Utils.valid_jwt_format?(response.body.to_s)
+            # It's a signed JWKS (JWT format)
+            jwks_jwt = response.body.to_s
+
+            # Convert entity statement keys to format expected by JWT gem
+            jwks_hash = Normalizer.to_jwks_hash(entity_statement_keys)
+
+            jwks_array = ::JWT.decode(
+              jwks_jwt,
+              nil,
+              true,
+              {algorithms: ["RS256"], jwks: jwks_hash}
+            )
+
+            # Extract JWKS from the decoded JWT payload
+            jwks_payload = jwks_array.first
+            Utils.to_indifferent_hash(jwks_payload)
+          else
+            # Standard JWKS JSON
+            json = response.parse(:json)
+            Utils.to_indifferent_hash(json)
+          end
+        else
+          # Standard JWKS without validation
+          json = response.parse(:json)
+          Utils.to_indifferent_hash(json)
+        end
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/jwks/normalizer.rb

@@ -0,0 +1,49 @@
+require "json"
+require_relative "../validators"
+
+# JWKS normalization utilities
+# Converts various JWKS formats to the format expected by JWT gem
+module OmniauthOpenidFederation
+  module Jwks
+    class Normalizer
+      # Convert JWKS to format expected by JWT gem
+      # Handles various input formats: Hash with "keys" or :keys, Array of keys, etc.
+      #
+      # @param jwks [Hash, Array, Object] JWKS in various formats
+      # @return [Hash] Normalized JWKS hash with "keys" array (string keys)
+      def self.to_jwks_hash(jwks)
+        if jwks.is_a?(Hash) && (jwks.key?("keys") || jwks.key?(:keys))
+          # Hash with keys array
+          keys = jwks["keys"] || jwks[:keys]
+          normalize_keys_array(keys)
+        elsif jwks.is_a?(Array)
+          # Array of keys
+          normalize_keys_array(jwks)
+        else
+          # Fallback: try to convert to hash
+          normalized = Validators.normalize_hash(jwks || {})
+          keys = normalized[:keys] || []
+          normalize_keys_array(keys)
+        end
+      end
+
+      # Normalize an array of JWK objects to hash format with string keys
+      #
+      # @param keys [Array] Array of JWK objects (Hash, etc.)
+      # @return [Hash] Hash with "keys" array containing normalized JWKs
+      def self.normalize_keys_array(keys)
+        {
+          "keys" => Array(keys).map do |jwk|
+            if jwk.is_a?(Hash)
+              jwk.stringify_keys
+            else
+              JSON.parse(jwk.to_json)
+            end
+          end
+        }
+      end
+
+      private_class_method :normalize_keys_array
+    end
+  end
+end

data/lib/omniauth_openid_federation/jwks/rotate.rb

@@ -0,0 +1,97 @@
+require_relative "../utils"
+require_relative "../logger"
+require_relative "../errors"
+require_relative "../configuration"
+require_relative "../string_helpers"
+require_relative "../entity_statement_reader"
+require_relative "fetch"
+require_relative "../federation/entity_statement_helper"
+require_relative "../federation/signed_jwks"
+
+# JWKS rotation service for OpenID Federation 1.0
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+#
+# Provides functionality to proactively refresh JWKS cache for providers.
+# This is useful for background jobs to refresh keys before they expire.
+#
+# Supports both standard JWKS and signed JWKS (OpenID Federation).
+module OmniauthOpenidFederation
+  module Jwks
+    # JWKS rotation service
+    #
+    # @example Rotate JWKS for a provider
+    #   OmniauthOpenidFederation::Jwks::Rotate.run(
+    #     "https://provider.example.com/.well-known/jwks.json",
+    #     entity_statement_path: "config/provider-entity-statement.jwt"
+    #   )
+    class Rotate
+      # Rotate JWKS cache for a provider
+      # This is useful for background jobs to proactively refresh keys
+      #
+      # @param jwks_uri [String] The JWKS URI to refresh
+      # @param entity_statement_path [String, nil] Path to entity statement file (optional)
+      # @return [Hash] The refreshed JWKS hash
+      # @raise [FetchError] If fetching fails
+      # @raise [ValidationError] If validation fails
+      # @raise [SecurityError] If path validation fails
+      # @raise [ConfigurationError] If entity statement file not found
+      def self.run(jwks_uri, entity_statement_path: nil)
+        if entity_statement_path
+          # Validate file path to prevent path traversal
+          begin
+            # Determine allowed directories for file path validation
+            config = Configuration.config
+            allowed_dirs = if defined?(Rails) && Rails.root
+              [Rails.root.join("config").to_s]
+            elsif config.root_path
+              [File.join(config.root_path, "config")]
+            end
+
+            validated_path = Utils.validate_file_path!(
+              entity_statement_path,
+              allowed_dirs: allowed_dirs
+            )
+          rescue SecurityError => e
+            Logger.error("[Jwks::Rotate] #{e.message}")
+            raise SecurityError, e.message
+          end
+
+          unless File.exist?(validated_path)
+            sanitized_path = Utils.sanitize_path(validated_path)
+            Logger.warn("[Jwks::Rotate] Entity statement file not found: #{sanitized_path}")
+            raise ConfigurationError, "Entity statement file not found: #{sanitized_path}"
+          end
+
+          # Try to use signed JWKS if entity statement is available
+          begin
+            parsed = Federation::EntityStatementHelper.parse_for_signed_jwks(validated_path)
+            if parsed && StringHelpers.present?(parsed[:signed_jwks_uri])
+              return Federation::SignedJWKS.fetch!(
+                parsed[:signed_jwks_uri],
+                parsed[:entity_jwks],
+                force_refresh: true
+              )
+            end
+          rescue SecurityError
+            raise
+          rescue
+            Logger.warn("[Jwks::Rotate] Failed to use signed JWKS, falling back to standard JWKS")
+          end
+
+          # Fallback to standard JWKS with entity statement keys
+          entity_statement_keys = EntityStatementReader.fetch_keys(
+            entity_statement_path: validated_path
+          )
+          return Fetch.run(
+            jwks_uri,
+            entity_statement_keys: entity_statement_keys,
+            force_refresh: true
+          )
+        end
+
+        # Use standard JWKS
+        Fetch.run(jwks_uri, force_refresh: true)
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/jwks/selector.rb

@@ -0,0 +1,101 @@
+require_relative "../logger"
+
+# JWKS Selector utilities for filtering keys
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+#
+# Provides utilities for selecting specific keys from a JWKS set, such as:
+# - Current keys (first signing and encryption keys)
+# - All keys (including previous keys for rotation support)
+# - Keys by use (signing vs encryption)
+# - Keys by kid (key ID)
+module OmniauthOpenidFederation
+  module Jwks
+    class Selector
+      # Get current keys from JWKS (first signing and encryption keys)
+      # This is useful for operations that only need the current keys, not all keys
+      # including previous keys from rotation.
+      #
+      # @param jwks [Hash, Array] JWKS hash with "keys" array or array of keys
+      # @return [Hash] JWKS hash with only current keys (one signing, one encryption)
+      def self.current_keys(jwks)
+        keys = extract_keys_array(jwks)
+        return {"keys" => []} if keys.empty?
+
+        taken_uses = []
+        current_keys = keys.select do |key|
+          use = key[:use] || key["use"]
+          if use == "sig" && !taken_uses.include?("sig")
+            taken_uses << "sig"
+            true
+          elsif use == "enc" && !taken_uses.include?("enc")
+            taken_uses << "enc"
+            true
+          else
+            false
+          end
+        end
+
+        {"keys" => current_keys}
+      end
+
+      # Get all keys from JWKS (including previous keys from rotation)
+      #
+      # @param jwks [Hash, Array] JWKS hash with "keys" array or array of keys
+      # @return [Hash] JWKS hash with all keys
+      def self.all_keys(jwks)
+        keys = extract_keys_array(jwks)
+        {"keys" => keys}
+      end
+
+      # Get signing keys only
+      #
+      # @param jwks [Hash, Array] JWKS hash with "keys" array or array of keys
+      # @return [Array<Hash>] Array of signing keys
+      def self.signing_keys(jwks)
+        keys = extract_keys_array(jwks)
+        keys.select { |key| (key[:use] || key["use"]) == "sig" }
+      end
+
+      # Get encryption keys only
+      #
+      # @param jwks [Hash, Array] JWKS hash with "keys" array or array of keys
+      # @return [Array<Hash>] Array of encryption keys
+      def self.encryption_keys(jwks)
+        keys = extract_keys_array(jwks)
+        keys.select { |key| (key[:use] || key["use"]) == "enc" }
+      end
+
+      # Get key by kid (key ID)
+      #
+      # @param jwks [Hash, Array] JWKS hash with "keys" array or array of keys
+      # @param kid [String] The key ID to find
+      # @return [Hash, nil] The key with matching kid, or nil if not found
+      def self.key_by_kid(jwks, kid)
+        keys = extract_keys_array(jwks)
+        keys.find { |key| (key[:kid] || key["kid"]) == kid }
+      end
+
+      # Extract keys array from various JWKS formats
+      #
+      # @param jwks [Hash, Array] JWKS in various formats
+      # @return [Array<Hash>] Array of key hashes
+      def self.extract_keys_array(jwks)
+        if jwks.is_a?(Hash)
+          if jwks.key?("keys")
+            jwks["keys"] || []
+          elsif jwks.key?(:keys)
+            jwks[:keys] || []
+          else
+            []
+          end
+        elsif jwks.is_a?(Array)
+          jwks
+        else
+          []
+        end
+      end
+
+      private_class_method :extract_keys_array
+    end
+  end
+end