omniauth_openid_federation 1.3.2 → 2.1.0

data/lib/omniauth_openid_federation/strategy/id_token_decoding.rb

@@ -0,0 +1,268 @@
+require "base64"
+require "jwt"
+
+require_relative "../secure_compare"
+
+module OmniauthOpenidFederation
+  module Strategy
+    module IdTokenDecoding
+      private
+
+      def decode_id_token(id_token)
+        client_options_hash = options.client_options || {}
+        normalized_options = OmniauthOpenidFederation::Validators.normalize_hash(client_options_hash)
+
+        if encrypted_token?(id_token)
+          decryption_key_source = options.decryption_key_source || options.key_source || :local
+          private_key = normalized_options[:private_key]
+          jwks = normalized_options[:jwks] || normalized_options["jwks"]
+          metadata = load_metadata_for_key_extraction
+
+          encryption_key = case decryption_key_source
+          when :federation
+            OmniauthOpenidFederation::KeyExtractor.extract_encryption_key(
+              jwks: jwks,
+              metadata: metadata,
+              private_key: private_key
+            )
+          when :local
+            private_key
+          else
+            raise OmniauthOpenidFederation::ConfigurationError, "Unknown decryption key source: #{decryption_key_source}"
+          end
+
+          OmniauthOpenidFederation::Validators.validate_private_key!(encryption_key)
+
+          begin
+            decrypted_token = OmniauthOpenidFederation::Jwe.decrypt(id_token, encryption_key)
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Successfully decrypted ID token using encryption key")
+
+            parts = decrypted_token.to_s.split(".")
+            if parts.length != 3
+              error_msg = "Decrypted token is not a valid JWT (expected 3 parts, got #{parts.length})"
+              OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+              OmniauthOpenidFederation::Instrumentation.notify_decryption_failed(
+                token_type: "id_token",
+                error_message: error_msg,
+                error_class: "DecryptionError"
+              )
+              raise OmniauthOpenidFederation::DecryptionError, error_msg
+            end
+
+            id_token = decrypted_token
+          rescue => e
+            error_msg = "Failed to decrypt ID token: #{e.class} - #{e.message}"
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            OmniauthOpenidFederation::Instrumentation.notify_decryption_failed(
+              token_type: "id_token",
+              error_message: e.message,
+              error_class: e.class.name
+            )
+            raise OmniauthOpenidFederation::DecryptionError, error_msg, e.backtrace
+          end
+        end
+
+        header_part = id_token.split(".").first
+        header = JSON.parse(Base64.urlsafe_decode64(header_part))
+        kid = header["kid"] || header[:kid]
+
+        OmniauthOpenidFederation::Logger.debug("[Strategy] ID token kid: #{kid}")
+
+        jwks = resolve_jwks_for_validation_with_kid(normalized_options, kid)
+
+        unless jwks
+          error_msg = "JWKS not available for ID token validation. Provide entity statement with provider JWKS or configure jwks_uri"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        begin
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Decoding ID token with JWKS (keys: #{(jwks.is_a?(Hash) && jwks["keys"]) ? jwks["keys"].length : "N/A"})")
+
+          unless jwks.is_a?(Hash) && jwks["keys"]
+            error_msg = "JWKS format invalid: expected hash with 'keys' array"
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            raise OmniauthOpenidFederation::ValidationError, error_msg
+          end
+
+          if kid.nil?
+            error_msg = "No key id (kid) found in JWT header. JWT must include kid in header to identify the signing key."
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            raise OmniauthOpenidFederation::SignatureError, error_msg
+          end
+
+          key_data = jwks["keys"].find { |key| (key["kid"] || key[:kid]) == kid }
+
+          unless key_data
+            available_kids = jwks["keys"].map { |k| k["kid"] || k[:kid] }.compact
+            error_msg = "Key with kid '#{kid}' not found in JWKS after trying all sources (entity statement, signed JWKS, standard JWKS URI). Available kids: #{available_kids.join(", ")}"
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            OmniauthOpenidFederation::Instrumentation.notify_kid_not_found(
+              kid: kid,
+              jwks_uri: resolve_jwks_uri(normalized_options),
+              available_kids: available_kids,
+              token_type: "id_token"
+            )
+            raise OmniauthOpenidFederation::ValidationError, error_msg
+          end
+
+          public_key = OmniauthOpenidFederation::KeyExtractor.jwk_to_openssl_key(key_data)
+
+          decoded_payload, _ = JWT.decode(
+            id_token,
+            public_key,
+            true,
+            {algorithm: "RS256"}
+          )
+
+          normalized_payload = decoded_payload.each_with_object({}) do |(k, v), h|
+            h[k.to_s] = v
+          end
+
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Successfully decoded ID token. Claims: #{normalized_payload.keys.join(", ")}")
+
+          required_claims = ["iss", "sub", "aud", "exp", "iat"]
+          payload_keys = normalized_payload.keys.map(&:to_s)
+          missing_claims = required_claims - payload_keys
+
+          if missing_claims.any?
+            error_msg = "ID token missing required claims: #{missing_claims.join(", ")}. Available claims: #{payload_keys.join(", ")}"
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            OmniauthOpenidFederation::Instrumentation.notify_missing_required_claims(
+              missing_claims: missing_claims,
+              available_claims: payload_keys,
+              token_type: "id_token"
+            )
+            raise OmniauthOpenidFederation::ValidationError, error_msg
+          end
+
+          validate_id_token_claims!(normalized_payload, normalized_options)
+          omniauth_rack_session&.delete("omniauth.nonce") if options.send_nonce
+
+          payload_with_symbols = normalized_payload.each_with_object({}) do |(k, v), h|
+            h[k.to_sym] = v
+          end
+
+          OmniauthOpenidFederation::IdToken.new(payload_with_symbols)
+        rescue JWT::DecodeError, JWT::VerificationError => e
+          error_msg = "Failed to decode or verify ID token signature: #{e.class} - #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+
+          available_kids = []
+          if jwks.is_a?(Hash) && jwks["keys"]
+            available_kids = jwks["keys"].map { |k| k["kid"] || k[:kid] }.compact
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Available keys in JWKS (kids): #{available_kids.join(", ")}")
+          end
+
+          OmniauthOpenidFederation::Instrumentation.notify_signature_verification_failed(
+            token_type: "id_token",
+            kid: kid,
+            jwks_uri: resolve_jwks_uri(normalized_options),
+            error_message: e.message,
+            error_class: e.class.name,
+            available_kids: available_kids
+          )
+
+          raise OmniauthOpenidFederation::SignatureError, error_msg, e.backtrace
+        rescue OmniauthOpenidFederation::ValidationError,
+          OmniauthOpenidFederation::SecurityError,
+          OmniauthOpenidFederation::ConfigurationError,
+          OmniauthOpenidFederation::DecryptionError => error
+          raise error
+        rescue => e
+          error_msg = "Failed to decode or validate ID token: #{e.class} - #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::SignatureError, error_msg, e.backtrace
+        end
+      end
+
+      def encrypted_token?(token)
+        OmniauthOpenidFederation::Jwe.encrypted?(token)
+      end
+
+      def validate_id_token_claims!(payload, normalized_options)
+        expected_issuer = expected_id_token_issuer(normalized_options)
+        token_issuer = payload["iss"]
+
+        if OmniauthOpenidFederation::StringHelpers.present?(expected_issuer) &&
+            token_issuer != expected_issuer
+          OmniauthOpenidFederation::Instrumentation.notify_issuer_mismatch(
+            expected_issuer: expected_issuer,
+            actual_issuer: token_issuer
+          )
+          raise OmniauthOpenidFederation::ValidationError,
+            "ID token issuer mismatch: expected '#{expected_issuer}', got '#{token_issuer}'"
+        end
+
+        expected_client_id = expected_id_token_client_id(normalized_options)
+        token_audiences = Array(payload["aud"]).map(&:to_s)
+
+        if OmniauthOpenidFederation::StringHelpers.present?(expected_client_id) &&
+            !token_audiences.include?(expected_client_id.to_s)
+          OmniauthOpenidFederation::Instrumentation.notify_audience_mismatch(
+            expected_audience: expected_client_id,
+            actual_audience: payload["aud"]
+          )
+          raise OmniauthOpenidFederation::ValidationError,
+            "ID token audience mismatch: expected '#{expected_client_id}' in aud, got '#{payload["aud"]}'"
+        end
+
+        if options.send_nonce
+          rack_session = omniauth_rack_session
+          unless rack_session
+            raise OmniauthOpenidFederation::ValidationError,
+              "ID token nonce validation failed: no nonce in session"
+          end
+
+          session_nonce = rack_session["omniauth.nonce"]
+          token_nonce = payload["nonce"]
+
+          if OmniauthOpenidFederation::StringHelpers.blank?(session_nonce)
+            raise OmniauthOpenidFederation::ValidationError,
+              "ID token nonce validation failed: no nonce in session"
+          end
+
+          if OmniauthOpenidFederation::StringHelpers.blank?(token_nonce) ||
+              !OmniauthOpenidFederation::SecureCompare.secure_compare(token_nonce.to_s, session_nonce.to_s)
+            OmniauthOpenidFederation::Instrumentation.notify_invalid_nonce(
+              expected_nonce: "[PRESENT]",
+              actual_nonce: token_nonce ? "[PRESENT]" : "[MISSING]"
+            )
+            raise OmniauthOpenidFederation::SecurityError, "ID token nonce mismatch"
+          end
+        end
+
+        OmniauthOpenidFederation::Validators.validate_allowed_acr_value!(
+          payload["acr"],
+          options.allowed_acr_values
+        )
+      end
+
+      def expected_id_token_issuer(normalized_options)
+        options.issuer ||
+          normalized_options[:issuer] ||
+          resolve_issuer_from_metadata
+      end
+
+      def expected_id_token_client_id(normalized_options)
+        if (options.client_registration_type || :explicit) == :automatic
+          client_entity_statement = load_client_entity_statement(
+            options.client_entity_statement_path,
+            options.client_entity_statement_url
+          )
+          entity_identifier = extract_entity_identifier_from_statement(
+            client_entity_statement,
+            options.client_entity_identifier
+          )
+          return entity_identifier if OmniauthOpenidFederation::StringHelpers.present?(entity_identifier)
+        end
+
+        if client.respond_to?(:identifier) && OmniauthOpenidFederation::StringHelpers.present?(client.identifier)
+          client.identifier
+        else
+          normalized_options[:identifier]
+        end
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/strategy/jwks_resolution.rb

@@ -0,0 +1,262 @@
+module OmniauthOpenidFederation
+  module Strategy
+    module JwksResolution
+      private
+
+      def resolve_jwks_for_validation(normalized_options)
+        entity_statement_content = load_provider_entity_statement
+
+        # 1. Extract JWKS directly from entity statement (we already have it - no HTTP request needed)
+        if entity_statement_content
+          begin
+            entity_statement = OmniauthOpenidFederation::Federation::EntityStatement.new(entity_statement_content)
+            parsed = entity_statement.parse
+            if parsed && parsed[:jwks]
+              entity_jwks = parsed[:jwks]
+              # Ensure it's in the format expected by JWT.decode (hash with "keys" array)
+              if entity_jwks.is_a?(Hash) && entity_jwks.key?("keys")
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Using JWKS from entity statement for ID token validation")
+                return entity_jwks
+              elsif entity_jwks.is_a?(Hash) && entity_jwks.key?(:keys)
+                # Convert symbol keys to string keys
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Using JWKS from entity statement for ID token validation")
+                return {"keys" => entity_jwks[:keys]}
+              elsif entity_jwks.is_a?(Array)
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Using JWKS from entity statement for ID token validation")
+                return {"keys" => entity_jwks}
+              end
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Could not extract JWKS from entity statement: #{e.message}")
+          end
+        end
+
+        # 2. Try to fetch from signed JWKS (if entity statement has signed_jwks_uri)
+        if entity_statement_content
+          begin
+            parsed = OmniauthOpenidFederation::Federation::EntityStatementHelper.parse_for_signed_jwks_from_content(
+              entity_statement_content
+            )
+            if parsed && parsed[:signed_jwks_uri] && parsed[:entity_jwks]
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Fetching signed JWKS for ID token validation")
+              signed_jwks = OmniauthOpenidFederation::Federation::SignedJWKS.fetch!(
+                parsed[:signed_jwks_uri],
+                parsed[:entity_jwks]
+              )
+              # Ensure it's in the format expected by JWT.decode
+              if signed_jwks.is_a?(Hash) && signed_jwks.key?("keys")
+                return signed_jwks
+              elsif signed_jwks.is_a?(Hash) && signed_jwks.key?(:keys)
+                return {"keys" => signed_jwks[:keys]}
+              elsif signed_jwks.is_a?(Array)
+                return {"keys" => signed_jwks}
+              end
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Could not fetch signed JWKS: #{e.message}")
+          end
+        end
+
+        # 3. Fallback: Fetch from standard JWKS URI (only if entity statement doesn't have JWKS)
+        jwks_uri = resolve_jwks_uri(normalized_options)
+        if OmniauthOpenidFederation::StringHelpers.present?(jwks_uri)
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Fetching JWKS from URI: #{OmniauthOpenidFederation::Utils.sanitize_uri(jwks_uri)}")
+          begin
+            return fetch_jwks(jwks_uri)
+          rescue => e
+            OmniauthOpenidFederation::Logger.warn("[Strategy] Failed to fetch JWKS from URI: #{e.message}")
+          end
+        end
+
+        # No JWKS found
+        nil
+      end
+
+      def resolve_jwks_for_validation_with_kid(normalized_options, kid)
+        entity_statement_content = load_provider_entity_statement
+        first_valid_jwks = nil # Track first valid JWKS in case kid is not found
+
+        # 1. Try entity statement JWKS first (fastest, no HTTP request)
+        if entity_statement_content
+          begin
+            entity_statement = OmniauthOpenidFederation::Federation::EntityStatement.new(entity_statement_content)
+            parsed = entity_statement.parse
+            if parsed && parsed[:jwks]
+              entity_jwks = parsed[:jwks]
+              # Ensure it's in the format expected by JWT.decode (hash with "keys" array)
+              jwks_hash = if entity_jwks.is_a?(Hash) && entity_jwks.key?("keys")
+                entity_jwks
+              elsif entity_jwks.is_a?(Hash) && entity_jwks.key?(:keys)
+                {"keys" => entity_jwks[:keys]}
+              elsif entity_jwks.is_a?(Array)
+                {"keys" => entity_jwks}
+              end
+
+              keys = jwks_hash&.dig("keys")
+              if keys&.is_a?(Array) && !keys.empty?
+                # Track first valid JWKS
+                first_valid_jwks ||= jwks_hash
+                # If kid is nil, return JWKS anyway (let JWT decoding fail with proper error)
+                if kid.nil?
+                  OmniauthOpenidFederation::Logger.debug("[Strategy] Kid is nil, returning entity statement JWKS for validation attempt")
+                  return jwks_hash
+                end
+                # Check if kid is in this JWKS
+                key_data = keys.find { |key| (key["kid"] || key[:kid]) == kid }
+                if key_data
+                  OmniauthOpenidFederation::Logger.debug("[Strategy] Found kid '#{kid}' in entity statement JWKS")
+                  return jwks_hash
+                else
+                  OmniauthOpenidFederation::Logger.debug("[Strategy] Kid '#{kid}' not found in entity statement JWKS, trying signed JWKS")
+                end
+              end
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Could not extract JWKS from entity statement: #{e.message}")
+          end
+        end
+
+        # 2. Try signed JWKS (if entity statement has signed_jwks_uri).
+        # When signed_jwks_uri is advertised, signature/validation failures fail closed
+        # instead of falling back to an unsigned jwks_uri.
+        if entity_statement_content
+          parsed = OmniauthOpenidFederation::Federation::EntityStatementHelper.parse_for_signed_jwks_from_content(
+            entity_statement_content
+          )
+          if parsed && parsed[:signed_jwks_uri] && parsed[:entity_jwks]
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Fetching signed JWKS for ID token validation (kid: #{kid})")
+            signed_jwks = OmniauthOpenidFederation::Federation::SignedJWKS.fetch!(
+              parsed[:signed_jwks_uri],
+              parsed[:entity_jwks]
+            )
+
+            jwks_hash = if signed_jwks.is_a?(Hash) && signed_jwks.key?("keys")
+              signed_jwks
+            elsif signed_jwks.is_a?(Hash) && signed_jwks.key?(:keys)
+              {"keys" => signed_jwks[:keys]}
+            elsif signed_jwks.is_a?(Array)
+              {"keys" => signed_jwks}
+            end
+
+            keys = jwks_hash&.dig("keys")
+            if keys&.is_a?(Array) && !keys.empty?
+              first_valid_jwks ||= jwks_hash
+              if kid.nil?
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Kid is nil, returning signed JWKS for validation attempt")
+                return jwks_hash
+              end
+              key_data = keys.find { |key| (key["kid"] || key[:kid]) == kid }
+              if key_data
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Found kid '#{kid}' in signed JWKS")
+                return jwks_hash
+              else
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Kid '#{kid}' not found in signed JWKS, trying standard JWKS URI")
+              end
+            end
+          end
+        end
+
+        # 3. Fallback: Fetch from standard JWKS URI
+        jwks_uri = resolve_jwks_uri(normalized_options)
+        if OmniauthOpenidFederation::StringHelpers.present?(jwks_uri)
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Fetching JWKS from URI for kid '#{kid}': #{OmniauthOpenidFederation::Utils.sanitize_uri(jwks_uri)}")
+          begin
+            jwks_hash = fetch_jwks(jwks_uri)
+            keys = jwks_hash&.dig("keys")
+            if keys&.is_a?(Array) && !keys.empty?
+              # Track first valid JWKS
+              first_valid_jwks ||= jwks_hash
+              # If kid is nil, return JWKS anyway (let JWT decoding fail with proper error)
+              if kid.nil?
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Kid is nil, returning standard JWKS URI for validation attempt")
+                return jwks_hash
+              end
+              # Check if kid is in this JWKS
+              key_data = keys.find { |key| (key["kid"] || key[:kid]) == kid }
+              if key_data
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Found kid '#{kid}' in standard JWKS URI")
+                return jwks_hash
+              else
+                OmniauthOpenidFederation::Logger.debug("[Strategy] Kid '#{kid}' not found in standard JWKS URI")
+              end
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.warn("[Strategy] Failed to fetch JWKS from URI: #{e.message}")
+          end
+        end
+
+        # If we found valid JWKS but kid was not found, return it anyway
+        # This allows the decoding to fail with "kid not found" instead of "JWKS not available"
+        if first_valid_jwks && kid
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Kid '#{kid}' not found in any JWKS source, but returning first valid JWKS for validation attempt")
+          return first_valid_jwks
+        end
+
+        # No JWKS found
+        nil
+      end
+
+      def resolve_jwks_uri(normalized_options)
+        # 1. Try client_options first
+        jwks_uri = normalized_options[:jwks_uri] || normalized_options["jwks_uri"]
+        if OmniauthOpenidFederation::StringHelpers.present?(jwks_uri)
+          # Build full URL if it's a path
+          if jwks_uri.start_with?("http://", "https://")
+            return jwks_uri
+          else
+            base_url = build_base_url(normalized_options)
+            return build_endpoint(base_url, jwks_uri) if base_url
+          end
+        end
+
+        # 2. Try to resolve from entity statement
+        if options.entity_statement_path
+          begin
+            resolved_endpoints = resolve_endpoints_from_metadata(normalized_options)
+            jwks_uri = resolved_endpoints[:jwks_uri] if resolved_endpoints[:jwks_uri]
+            if OmniauthOpenidFederation::StringHelpers.present?(jwks_uri)
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Resolved JWKS URI from entity statement: #{jwks_uri}")
+              return jwks_uri
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Could not get JWKS URI from entity statement: #{e.message}")
+          end
+        end
+
+        # 3. Try to get from OpenID Connect client
+        begin
+          if client.respond_to?(:jwks_uri) && client.jwks_uri
+            jwks_uri = client.jwks_uri.to_s
+            if OmniauthOpenidFederation::StringHelpers.present?(jwks_uri)
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Using JWKS URI from client: #{jwks_uri}")
+              return jwks_uri
+            end
+          end
+        rescue => e
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Could not get JWKS URI from client: #{e.message}")
+        end
+
+        # No JWKS URI found
+        nil
+      end
+
+      def fetch_jwks(jwks_uri)
+        # Use our JWKS fetching logic
+        # Returns a hash with "keys" array that JWT.decode can use directly
+        jwks = OmniauthOpenidFederation::Jwks::Fetch.run(jwks_uri)
+
+        # Ensure it's in the format expected by JWT.decode (hash with "keys" array)
+        if jwks.is_a?(Hash) && jwks.key?("keys")
+          # Already in correct format - JWT.decode accepts this directly
+          jwks
+        elsif jwks.is_a?(Array)
+          # If it's an array of keys, wrap it in a hash
+          {"keys" => jwks}
+        else
+          # Fallback: wrap in keys array
+          {"keys" => [jwks].compact}
+        end
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/strategy/provider_entity_statement.rb

@@ -0,0 +1,135 @@
+module OmniauthOpenidFederation
+  module Strategy
+    module ProviderEntityStatement
+      private
+
+      def resolve_entity_statement_path(path)
+        if path.start_with?("/")
+          path
+        elsif defined?(Rails) && Rails.root
+          Rails.root.join(path).to_s
+        else
+          File.expand_path(path)
+        end
+      end
+
+      def load_provider_entity_statement
+        # Priority 1: Use file path if provided
+        if OmniauthOpenidFederation::StringHelpers.present?(options.entity_statement_path)
+          path = resolve_entity_statement_path(options.entity_statement_path)
+          if File.exist?(path)
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Loading provider entity statement from file: #{path}")
+            return File.read(path).strip
+          end
+
+          raise OmniauthOpenidFederation::ConfigurationError,
+            "Provider entity statement file not found: #{path}"
+        end
+
+        # Priority 2: Fetch from URL if provided
+        if OmniauthOpenidFederation::StringHelpers.present?(options.entity_statement_url)
+          return fetch_and_cache_entity_statement(
+            options.entity_statement_url,
+            fingerprint: options.entity_statement_fingerprint
+          )
+        end
+
+        # Priority 3: Fetch from issuer if provided (only if issuer is a valid URL)
+        if OmniauthOpenidFederation::StringHelpers.present?(options.issuer)
+          # Check that issuer is a valid URL format before trying to fetch
+          # Note: Config values are trusted, only basic format check needed
+          begin
+            parsed_issuer = URI.parse(options.issuer)
+            unless parsed_issuer.is_a?(URI::HTTP) || parsed_issuer.is_a?(URI::HTTPS)
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Issuer is not a valid HTTP/HTTPS URL, skipping entity statement fetch from URL: #{options.issuer}")
+              return nil
+            end
+          rescue URI::InvalidURIError
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Issuer is not a valid URL, skipping entity statement fetch from URL: #{options.issuer}")
+            return nil
+          end
+
+          entity_statement_url = OmniauthOpenidFederation::Utils.build_entity_statement_url(options.issuer)
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Building entity statement URL from issuer: #{entity_statement_url}")
+          return fetch_and_cache_entity_statement(
+            entity_statement_url,
+            fingerprint: options.entity_statement_fingerprint
+          )
+        end
+
+        nil
+      end
+
+      def fetch_and_cache_entity_statement(url, fingerprint: nil)
+        cache_key = "federation:provider_entity_statement:#{Digest::SHA256.hexdigest(url)}"
+
+        # Check cache first (if Rails.cache is available)
+        if defined?(Rails) && Rails.cache
+          begin
+            cached = Rails.cache.read(cache_key)
+            if cached
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Using cached provider entity statement from: #{url}")
+              return cached
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.debug("[Strategy] Cache read failed, fetching fresh: #{e.message}")
+          end
+        end
+
+        # Fetch from URL
+        OmniauthOpenidFederation::Logger.info("[Strategy] Fetching provider entity statement from: #{url}")
+        begin
+          statement = OmniauthOpenidFederation::Federation::EntityStatement.fetch!(
+            url,
+            fingerprint: fingerprint,
+            timeout: 10
+          )
+
+          entity_statement_content = statement.entity_statement
+
+          # Cache the fetched statement (if Rails.cache is available)
+          if defined?(Rails) && Rails.cache
+            begin
+              # Cache for 1 hour (entity statements typically expire after 24 hours)
+              Rails.cache.write(cache_key, entity_statement_content, expires_in: 3600)
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Cached provider entity statement from: #{url}")
+            rescue => e
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Cache write failed: #{e.message}")
+            end
+          end
+
+          entity_statement_content
+        rescue OmniauthOpenidFederation::FetchError, OmniauthOpenidFederation::ValidationError => e
+          error_msg = "Failed to fetch provider entity statement from #{url}: #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+      end
+
+      def load_metadata_for_key_extraction
+        entity_statement_content = load_provider_entity_statement
+        return nil unless entity_statement_content
+
+        begin
+          # Parse entity statement to extract metadata and JWKS from content
+          parsed = OmniauthOpenidFederation::Federation::EntityStatementHelper.parse_for_signed_jwks_from_content(
+            entity_statement_content
+          )
+
+          return nil unless parsed && parsed[:metadata]
+
+          # Return metadata in format expected by KeyExtractor
+          # KeyExtractor expects metadata hash that may contain JWKS
+          metadata = parsed[:metadata]
+          entity_jwks = parsed[:entity_jwks] || metadata[:jwks] || {}
+
+          # Return metadata with JWKS included
+          metadata.merge(jwks: entity_jwks)
+        rescue => e
+          OmniauthOpenidFederation::Logger.warn("[Strategy] Failed to load metadata from entity statement for key extraction: #{e.message}")
+          nil
+        end
+      end
+    end
+  end
+end