omniauth_openid_federation 1.3.0 → 2.0.0

data/lib/omniauth_openid_federation/strategy/authorization_request.rb

@@ -0,0 +1,220 @@
+module OmniauthOpenidFederation
+  module Strategy
+    module AuthorizationRequest
+      def authorize_uri
+        validate_provider_trust_configuration!
+
+        request_params = request.params
+
+        # Security: Only validate user input from HTTP requests, not config values
+        # Note: Rack params can return arrays for multi-value parameters
+        sanitized_params = {}
+        request_params.each do |key, value|
+          next unless value
+          key_str = key.to_s
+          next if key_str.length > 256
+          # For arrays (multi-value params), sanitize each element and limit size
+          if value.is_a?(Array)
+            # Prevent DoS: limit array size
+            if value.length > 100
+              next
+            end
+            # Sanitize each element
+            sanitized_array = value.map { |v| OmniauthOpenidFederation::Validators.sanitize_request_param(v) }.compact
+            next if sanitized_array.empty?
+            # Keep as array for acr_values (handled by normalize_acr_values)
+            # Convert to space-separated string for other parameters (ui_locales, claims_locales)
+            sanitized_params[key_str] = if key_str == "acr_values"
+              sanitized_array
+            else
+              sanitized_array.join(" ")
+            end
+          else
+            sanitized = OmniauthOpenidFederation::Validators.sanitize_request_param(value)
+            sanitized_params[key_str] = sanitized if sanitized
+          end
+        end
+        request_params = sanitized_params
+
+        if options.default_request_object_claims.is_a?(Hash)
+          options.default_request_object_claims.each do |key, value|
+            key_str = key.to_s
+            next if key_str.length > 256
+            next if OmniauthOpenidFederation::StringHelpers.blank?(value)
+            request_params[key_str] ||= value
+          end
+        end
+
+        # Apply custom proc to modify params before adding to signed request object
+        if options.prepare_request_object_params.respond_to?(:call)
+          request_params = options.prepare_request_object_params.call(request_params.dup) || request_params
+          request_params = {} unless request_params.is_a?(Hash)
+        end
+
+        # Enforce signed request objects (RFC 9101) - unsigned requests are not allowed
+        client_options_hash = options.client_options || {}
+        normalized_options = OmniauthOpenidFederation::Validators.normalize_hash(client_options_hash)
+        private_key = normalized_options[:private_key]
+        OmniauthOpenidFederation::Validators.validate_private_key!(private_key)
+
+        resolved_issuer = options.issuer
+        unless OmniauthOpenidFederation::StringHelpers.present?(resolved_issuer)
+          resolved_issuer = resolve_issuer_from_metadata
+          options.issuer = resolved_issuer if resolved_issuer
+        end
+
+        audience_value = resolve_audience(client_options_hash, resolved_issuer)
+
+        unless OmniauthOpenidFederation::StringHelpers.present?(audience_value)
+          error_msg = "Audience is required for signed request objects. " \
+                      "Set audience option, provide entity statement with provider issuer, or configure token_endpoint"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        state_value = new_state
+        nonce_value = options.send_nonce ? new_nonce : nil
+        configured_redirect_uri = normalized_options[:redirect_uri] || callback_url
+
+        # Automatic registration uses entity identifier as client_id (OpenID Federation Section 12.1)
+        client_registration_type = options.client_registration_type || :explicit
+        client_id_for_request = normalized_options[:identifier]
+        client_entity_statement = nil
+
+        if client_registration_type == :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)
+          unless OmniauthOpenidFederation::StringHelpers.present?(entity_identifier)
+            error_msg = "Failed to extract entity identifier from client entity statement. " \
+                        "Set client_entity_identifier option or ensure entity statement has 'sub' claim"
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            raise OmniauthOpenidFederation::ConfigurationError, error_msg
+          end
+          client_id_for_request = entity_identifier
+          if client.respond_to?(:identifier=)
+            client.identifier = entity_identifier
+          elsif client.respond_to?(:client_id=)
+            client.client_id = entity_identifier
+          end
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Using automatic registration with entity identifier: #{entity_identifier}")
+        end
+
+        signing_key_source = options.signing_key_source || options.key_source || :local
+        jwks = normalized_options[:jwks] || normalized_options["jwks"]
+
+        # Extract already-sanitized user input params (sanitized above)
+        validated_state = state_value.to_s.strip
+        validated_nonce = nonce_value&.to_s&.strip
+        validated_login_hint = request_params["login_hint"]
+        validated_ui_locales = request_params["ui_locales"]
+        validated_claims_locales = request_params["claims_locales"]
+
+        # Config values are trusted (no sanitization needed)
+        validated_client_id = client_id_for_request.to_s.strip
+        validated_redirect_uri = configured_redirect_uri.to_s.strip
+        validated_scope = Array(options.scope).join(" ").strip
+        validated_response_type = options.response_type.to_s.strip
+        validated_prompt = options.prompt&.to_s&.strip
+        validated_hd = options.hd&.to_s&.strip
+        validated_response_mode = options.response_mode&.to_s&.strip
+        validated_issuer = (resolved_issuer || options.issuer)&.to_s&.strip
+        validated_audience = audience_value&.to_s&.strip
+        normalized_acr_values = OmniauthOpenidFederation::Validators.normalize_acr_values(request_params["acr_values"], skip_sanitization: true) || nil
+
+        request_object_claims = request_params.dup
+        request_object_claims["acr_values"] = normalized_acr_values if normalized_acr_values
+        request_object_claims["ui_locales"] = validated_ui_locales if validated_ui_locales
+        request_object_claims["claims_locales"] = validated_claims_locales if validated_claims_locales
+        request_object_claims["login_hint"] = validated_login_hint if validated_login_hint
+        OmniauthOpenidFederation::Validators.validate_required_request_object_claims!(
+          request_object_claims,
+          options.required_request_object_claims
+        )
+
+        jws_builder = OmniauthOpenidFederation::Jws.new(
+          client_id: validated_client_id,
+          redirect_uri: validated_redirect_uri,
+          scope: validated_scope,
+          issuer: validated_issuer,
+          audience: validated_audience,
+          state: validated_state,
+          nonce: validated_nonce,
+          response_type: validated_response_type,
+          response_mode: validated_response_mode,
+          login_hint: validated_login_hint,
+          ui_locales: validated_ui_locales,
+          claims_locales: validated_claims_locales,
+          prompt: validated_prompt,
+          hd: validated_hd,
+          acr_values: normalized_acr_values,
+          extra_params: options.extra_authorize_params || {},
+          private_key: normalized_options[:private_key],
+          jwks: jwks,
+          entity_statement_path: options.entity_statement_path,
+          key_source: signing_key_source,
+          client_entity_statement: client_entity_statement
+        )
+
+        # Add dynamic request object params from HTTP request (already sanitized above)
+        options.request_object_params&.each do |key|
+          key_str = key.to_s
+          next if key_str.length > 256
+          value = request_params[key_str]
+          jws_builder.add_claim(key_str.to_sym, value) if value
+        end
+
+        # RFC 9101: Only 'request' parameter in query, all params in JWT
+        provider_metadata = load_provider_metadata_for_encryption
+        signed_request_object = jws_builder.sign(
+          provider_metadata: provider_metadata,
+          always_encrypt: options.always_encrypt_request_object
+        )
+        unless OmniauthOpenidFederation::StringHelpers.present?(signed_request_object)
+          error_msg = "Failed to generate signed request object - authentication cannot proceed without signed request"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::SecurityError, error_msg
+        end
+
+        # Build URL manually to ensure RFC 9101 compliance (only 'request' param in query)
+        auth_endpoint = client.authorization_endpoint
+        unless OmniauthOpenidFederation::StringHelpers.present?(auth_endpoint)
+          error_msg = "Authorization endpoint not configured. Provide authorization_endpoint in client_options or entity statement"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        begin
+          uri = URI.parse(auth_endpoint)
+        rescue URI::InvalidURIError => e
+          error_msg = "Invalid authorization endpoint URI format: #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        max_string_length = ::OmniauthOpenidFederation::Configuration.config.max_string_length
+        if signed_request_object.length > max_string_length
+          OmniauthOpenidFederation::Logger.warn("[Strategy] Request object exceeds maximum length")
+        end
+
+        uri.query = URI.encode_www_form(request: signed_request_object)
+        uri.to_s
+      end
+
+      def validate_provider_trust_configuration!
+        return unless options.require_entity_statement_fingerprint
+
+        using_remote_source = OmniauthOpenidFederation::StringHelpers.present?(options.entity_statement_url) ||
+          OmniauthOpenidFederation::StringHelpers.present?(options.issuer)
+        return unless using_remote_source
+
+        if OmniauthOpenidFederation::StringHelpers.blank?(options.entity_statement_fingerprint)
+          raise OmniauthOpenidFederation::ConfigurationError,
+            "entity_statement_fingerprint is required when require_entity_statement_fingerprint is enabled"
+        end
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/strategy/callback_handling.rb

@@ -0,0 +1,135 @@
+module OmniauthOpenidFederation
+  module Strategy
+    module CallbackHandling
+      def callback_phase
+        # Security: Validate user input from HTTP request
+        state_param_raw = request.params["state"]
+        code_param_raw = request.params["code"]
+        error_param_raw = request.params["error"]
+        error_description_raw = request.params["error_description"]
+
+        state_param = state_param_raw ? OmniauthOpenidFederation::Validators.sanitize_request_param(state_param_raw) : nil
+        code_param = code_param_raw ? OmniauthOpenidFederation::Validators.sanitize_request_param(code_param_raw) : nil
+        error_param = error_param_raw ? OmniauthOpenidFederation::Validators.sanitize_request_param(error_param_raw) : nil
+        error_description_param = error_description_raw ? OmniauthOpenidFederation::Validators.sanitize_request_param(error_description_raw) : nil
+        if error_param
+          error_msg = "Authorization error: #{error_param}"
+          error_msg += " - #{error_description_param}" if error_description_param
+          OmniauthOpenidFederation::Instrumentation.notify_unexpected_authentication_break(
+            stage: "callback_phase",
+            error_message: error_msg,
+            error_class: "AuthorizationError",
+            request_info: {
+              remote_ip: request.env["REMOTE_ADDR"],
+              user_agent: request.env["HTTP_USER_AGENT"],
+              path: request.path
+            }
+          )
+          env["omniauth_openid_federation.instrumented"] = true
+          return fail!(:authorization_error, OmniauthOpenidFederation::ValidationError.new(error_msg))
+        end
+
+        # CSRF protection: constant-time state comparison
+        state_session = session["omniauth.state"]
+
+        if OmniauthOpenidFederation::StringHelpers.blank?(state_param) ||
+            state_session.nil? ||
+            !OmniauthOpenidFederation::SecureCompare.secure_compare(state_param.to_s, state_session.to_s)
+          # Instrument CSRF detection
+          OmniauthOpenidFederation::Instrumentation.notify_csrf_detected(
+            state_param: state_param ? "[PRESENT]" : "[MISSING]",
+            state_session: state_session ? "[PRESENT]" : "[MISSING]",
+            request_info: {
+              remote_ip: request.env["REMOTE_ADDR"],
+              user_agent: request.env["HTTP_USER_AGENT"],
+              path: request.path
+            }
+          )
+          # Mark as instrumented to prevent double instrumentation in fail!
+          env["omniauth_openid_federation.instrumented"] = true
+          return fail!(:csrf_detected, OmniauthOpenidFederation::SecurityError.new("CSRF detected"))
+        end
+
+        # Clear state from session
+        session.delete("omniauth.state")
+
+        if OmniauthOpenidFederation::StringHelpers.blank?(code_param)
+          # Instrument unexpected authentication break
+          OmniauthOpenidFederation::Instrumentation.notify_unexpected_authentication_break(
+            stage: "callback_phase",
+            error_message: "Missing authorization code",
+            error_class: "ValidationError",
+            request_info: {
+              remote_ip: request.env["REMOTE_ADDR"],
+              user_agent: request.env["HTTP_USER_AGENT"],
+              path: request.path
+            }
+          )
+          # Mark as instrumented to prevent double instrumentation in fail!
+          env["omniauth_openid_federation.instrumented"] = true
+          return fail!(:missing_code, OmniauthOpenidFederation::ValidationError.new("Missing authorization code"))
+        end
+
+        begin
+          @access_token = exchange_authorization_code(code_param)
+        rescue => e
+          # Instrument unexpected authentication break
+          OmniauthOpenidFederation::Instrumentation.notify_unexpected_authentication_break(
+            stage: "token_exchange",
+            error_message: e.message,
+            error_class: e.class.name,
+            request_info: {
+              remote_ip: request.env["REMOTE_ADDR"],
+              user_agent: request.env["HTTP_USER_AGENT"],
+              path: request.path
+            }
+          )
+          # Mark as instrumented to prevent double instrumentation in fail!
+          env["omniauth_openid_federation.instrumented"] = true
+          return fail!(:token_exchange_error, e)
+        end
+
+        env["omniauth.auth"] = auth_hash
+        call_app!
+      end
+
+      private
+
+      def exchange_authorization_code(authorization_code)
+        client_options_hash = options.client_options || {}
+        normalized_options = OmniauthOpenidFederation::Validators.normalize_hash(client_options_hash)
+        configured_redirect_uri = normalized_options[:redirect_uri] || callback_url
+
+        oidc_client.authorization_code = authorization_code
+        oidc_client.redirect_uri = configured_redirect_uri
+
+        begin
+          oidc_client.access_token!(
+            options.client_auth_method || :jwt_bearer
+          )
+        rescue => e
+          error_msg = "Failed to exchange authorization code for access token: #{e.class} - #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::NetworkError, error_msg, e.backtrace
+        end
+      end
+
+      def new_state
+        # Generate a random state value and store it in the session
+        state = SecureRandom.hex(self.class::STATE_BYTES)
+        session["omniauth.state"] = state
+        state
+      end
+
+      def new_nonce
+        nonce = SecureRandom.hex(self.class::NONCE_BYTES)
+        session["omniauth.nonce"] = nonce if options.send_nonce
+        nonce
+      end
+
+      def omniauth_rack_session
+        env.is_a?(Hash) ? env["rack.session"] : nil
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/strategy/client_construction.rb

@@ -0,0 +1,101 @@
+module OmniauthOpenidFederation
+  module Strategy
+    module ClientConstruction
+      def client_jwk_signing_key
+        # Return manually configured value if present (allows override)
+        configured_value = options.client_jwk_signing_key
+        return configured_value if OmniauthOpenidFederation::StringHelpers.present?(configured_value)
+
+        # Automatically extract from client entity statement if available
+        extracted_value = extract_client_jwk_signing_key
+        return extracted_value if OmniauthOpenidFederation::StringHelpers.present?(extracted_value)
+
+        # Return nil if not available (allows fallback to other authentication methods)
+        nil
+      end
+
+      def options
+        opts = super
+        # Dynamically set client_jwk_signing_key if not already set and we can extract it
+        if opts[:client_jwk_signing_key].nil? && (opts[:client_entity_statement_path] || opts[:client_entity_statement_url])
+          extracted = extract_client_jwk_signing_key
+          opts[:client_jwk_signing_key] = extracted if OmniauthOpenidFederation::StringHelpers.present?(extracted)
+        end
+        opts
+      end
+
+      def client
+        @client ||= begin
+          client_options_hash = options.client_options || {}
+
+          # Automatically resolve endpoints, issuer, scheme, and host from entity statement metadata if available
+          # This allows endpoints and issuer to be discovered from entity statement without manual configuration
+          # client_options still takes precedence for overrides
+          resolved_endpoints = resolve_endpoints_from_metadata(client_options_hash)
+
+          # Merge resolved endpoints with client_options (client_options takes precedence)
+          # resolved_endpoints may contain: endpoints, issuer, scheme, host
+          # client_options will override any resolved values
+          merged_options = resolved_endpoints.merge(client_options_hash)
+
+          # Build base URL from scheme, host, and port
+          base_url = build_base_url(merged_options)
+
+          # For automatic registration, identifier is the entity identifier (determined at request time)
+          # For explicit registration, identifier comes from client_options
+          # Note: For automatic registration, the actual entity identifier will be extracted
+          # in authorize_uri and used in the request object. The client identifier here is
+          # used for client assertion at the token endpoint, which should also use the entity identifier.
+          # However, since the client is cached, we'll handle this in authorize_uri by updating
+          # the client's identifier if needed.
+          client_identifier = merged_options[:identifier] || merged_options["identifier"]
+
+          # Create OpenID Connect client (extends OAuth2::Client, so compatible with OmniAuth::Strategies::OAuth2)
+          # Build endpoints - use resolved values or nil if not available
+          auth_endpoint = build_endpoint(base_url, merged_options[:authorization_endpoint] || merged_options["authorization_endpoint"])
+          token_endpoint = build_endpoint(base_url, merged_options[:token_endpoint] || merged_options["token_endpoint"])
+          userinfo_endpoint = build_endpoint(base_url, merged_options[:userinfo_endpoint] || merged_options["userinfo_endpoint"])
+          jwks_uri_endpoint = build_endpoint(base_url, merged_options[:jwks_uri] || merged_options["jwks_uri"])
+
+          # Validate that at least authorization_endpoint is present (required)
+          unless OmniauthOpenidFederation::StringHelpers.present?(auth_endpoint)
+            error_msg = "Authorization endpoint not configured. Provide authorization_endpoint in client_options or entity statement"
+            OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+            raise OmniauthOpenidFederation::ConfigurationError, error_msg
+          end
+
+          oidc_client = OmniauthOpenidFederation::OidcClient.new(
+            identifier: client_identifier,
+            secret: nil, # We use private_key_jwt, so no secret needed
+            redirect_uri: merged_options[:redirect_uri] || merged_options["redirect_uri"],
+            authorization_endpoint: auth_endpoint,
+            token_endpoint: token_endpoint,
+            userinfo_endpoint: userinfo_endpoint,
+            jwks_uri: jwks_uri_endpoint
+          )
+
+          # Store private key for client assertion (private_key_jwt authentication)
+          oidc_client.private_key = merged_options[:private_key] || merged_options["private_key"]
+
+          # Store strategy options on client for AccessToken to access later
+          # This allows AccessToken to get configuration without relying on Devise
+          # Ensure all entity statement options are included (to_h might not include all options)
+          strategy_options_hash = options.to_h.dup
+          # Explicitly include entity statement options that AccessToken needs
+          strategy_options_hash[:entity_statement_path] = options.entity_statement_path if options.entity_statement_path
+          strategy_options_hash[:entity_statement_url] = options.entity_statement_url if options.entity_statement_url
+          strategy_options_hash[:entity_statement_fingerprint] = options.entity_statement_fingerprint if options.entity_statement_fingerprint
+          strategy_options_hash[:issuer] = options.issuer if options.issuer
+          oidc_client.instance_variable_set(:@strategy_options, strategy_options_hash)
+
+          # OidcClient extends OAuth2::Client, so it's compatible with OmniAuth::Strategies::OAuth2
+          oidc_client
+        end
+      end
+
+      def oidc_client
+        client
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/strategy/client_entity_statement.rb

@@ -0,0 +1,211 @@
+module OmniauthOpenidFederation
+  module Strategy
+    module ClientEntityStatement
+      private
+
+      def load_client_entity_statement(entity_statement_path = nil, entity_statement_url = nil)
+        # Priority 1: Use file path if provided (for manual cache, development, debugging)
+        if OmniauthOpenidFederation::StringHelpers.present?(entity_statement_path)
+          return load_client_entity_statement_from_file(entity_statement_path)
+        end
+
+        # Priority 2: Check cache (if Rails.cache is available)
+        # This respects background job cache refresh and key rotation
+        if defined?(Rails) && Rails.cache
+          cache_key = "federation:entity_statement"
+          config = OmniauthOpenidFederation::FederationEndpoint.configuration
+
+          # Use cache TTL based on entity statement expiration or default to 1 hour
+          # The entity statement JWT itself has an expiration, but we cache it for performance
+          # Cache TTL should be shorter than JWT expiration to ensure fresh keys
+          cache_ttl = config.jwks_cache_ttl || 3600 # Default to 1 hour, same as JWKS cache
+
+          begin
+            cached_statement = Rails.cache.fetch(cache_key, expires_in: cache_ttl) do
+              # Generate and cache if not in cache
+              entity_statement = OmniauthOpenidFederation::FederationEndpoint.generate_entity_statement
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Generated and cached client entity statement")
+              entity_statement
+            end
+
+            if cached_statement
+              OmniauthOpenidFederation::Logger.debug("[Strategy] Using cached client entity statement")
+              return cached_statement
+            end
+          rescue => e
+            OmniauthOpenidFederation::Logger.warn("[Strategy] Cache fetch failed, generating fresh entity statement: #{e.message}")
+            # Fall through to generate dynamically
+          end
+        end
+
+        # Priority 3: Generate dynamically (always available)
+        # The entity statement is always generated via FederationEndpoint
+        begin
+          entity_statement = OmniauthOpenidFederation::FederationEndpoint.generate_entity_statement
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Generated client entity statement dynamically")
+          entity_statement
+        rescue OmniauthOpenidFederation::ConfigurationError => e
+          # FederationEndpoint not configured - provide helpful error message
+          error_msg = "Failed to generate client entity statement: #{e.message}. " \
+                      "Either configure OmniauthOpenidFederation::FederationEndpoint.configure " \
+                      "or provide client_entity_statement_path for manual cache/dev/debug."
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        rescue => e
+          error_msg = "Failed to generate client entity statement: #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+      end
+
+      def load_client_entity_statement_from_file(entity_statement_path)
+        # Resolve path (relative to Rails root if available)
+        path = if entity_statement_path.start_with?("/")
+          entity_statement_path
+        elsif defined?(Rails) && Rails.root
+          Rails.root.join(entity_statement_path).to_s
+        else
+          File.expand_path(entity_statement_path)
+        end
+
+        unless File.exist?(path)
+          error_msg = "Client entity statement file not found: #{path}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        entity_statement = File.read(path)
+        unless OmniauthOpenidFederation::StringHelpers.present?(entity_statement)
+          error_msg = "Client entity statement file is empty: #{path}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        # Validate it's a JWT (has 3 parts)
+        jwt_parts = entity_statement.strip.split(".")
+        unless jwt_parts.length == 3
+          error_msg = "Client entity statement is not a valid JWT (expected 3 parts, got #{jwt_parts.length}): #{path}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        entity_statement.strip
+      end
+
+      def load_client_entity_statement_from_url(entity_statement_url)
+        response = HttpClient.get(entity_statement_url)
+        unless response.status.success?
+          error_msg = "Failed to fetch client entity statement from #{entity_statement_url}: HTTP #{response.status}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        entity_statement = response.body.to_s
+        unless OmniauthOpenidFederation::StringHelpers.present?(entity_statement)
+          error_msg = "Client entity statement from URL is empty: #{entity_statement_url}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        # Validate it's a JWT (has 3 parts)
+        jwt_parts = entity_statement.strip.split(".")
+        unless jwt_parts.length == 3
+          error_msg = "Client entity statement from URL is not a valid JWT (expected 3 parts, got #{jwt_parts.length}): #{entity_statement_url}"
+          OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+          raise OmniauthOpenidFederation::ConfigurationError, error_msg
+        end
+
+        entity_statement.strip
+      rescue OmniauthOpenidFederation::NetworkError => e
+        error_msg = "Failed to fetch client entity statement from #{entity_statement_url}: #{e.message}"
+        OmniauthOpenidFederation::Logger.error("[Strategy] #{error_msg}")
+        raise OmniauthOpenidFederation::ConfigurationError, error_msg
+      end
+
+      def extract_client_jwk_signing_key
+        # Access raw options hash to avoid recursion (don't call options method which triggers extraction)
+        raw_opts = @options || {}
+
+        # If explicit JWKS is provided, use it
+        return raw_opts[:client_jwk_signing_key] if OmniauthOpenidFederation::StringHelpers.present?(raw_opts[:client_jwk_signing_key])
+
+        # Entity statement is always available (either from file or generated dynamically)
+        begin
+          entity_statement_content = load_client_entity_statement(
+            raw_opts[:client_entity_statement_path],
+            raw_opts[:client_entity_statement_url]
+          )
+          return nil unless OmniauthOpenidFederation::StringHelpers.present?(entity_statement_content)
+
+          # Extract JWKS from client entity statement
+          jwt_parts = entity_statement_content.split(".")
+          return nil if jwt_parts.length != 3
+
+          payload = JSON.parse(Base64.urlsafe_decode64(jwt_parts[1]))
+          entity_jwks = payload.fetch("jwks", {})
+          return nil if entity_jwks.empty?
+
+          # Return JWKS as JSON string (format expected by OAuth2/OIDC clients)
+          JSON.dump(entity_jwks)
+        rescue => e
+          OmniauthOpenidFederation::Logger.warn("[Strategy] Failed to extract client JWKS from entity statement: #{e.message}")
+          nil
+        end
+      end
+
+      def extract_entity_identifier_from_statement(entity_statement, configured_identifier = nil)
+        # Use configured identifier if provided
+        return configured_identifier if OmniauthOpenidFederation::StringHelpers.present?(configured_identifier)
+
+        # Extract from entity statement
+        begin
+          jwt_parts = entity_statement.split(".")
+          payload = JSON.parse(Base64.urlsafe_decode64(jwt_parts[1]))
+          entity_identifier = payload["sub"] || payload[:sub]
+          return entity_identifier if OmniauthOpenidFederation::StringHelpers.present?(entity_identifier)
+
+          # Fallback to issuer if sub is not present
+          entity_identifier = payload["iss"] || payload[:iss]
+          return entity_identifier if OmniauthOpenidFederation::StringHelpers.present?(entity_identifier)
+
+          OmniauthOpenidFederation::Logger.warn("[Strategy] Could not extract entity identifier from entity statement (no 'sub' or 'iss' claim)")
+          nil
+        rescue => e
+          OmniauthOpenidFederation::Logger.error("[Strategy] Failed to extract entity identifier from entity statement: #{e.message}")
+          nil
+        end
+      end
+
+      def load_provider_metadata_for_encryption
+        entity_statement_content = load_provider_entity_statement
+        return nil unless entity_statement_content
+
+        begin
+          # Decode entity statement payload to get all provider metadata fields
+          # EntityStatement.parse only extracts specific fields, so we need to access raw payload
+          jwt_parts = entity_statement_content.split(".")
+          return nil if jwt_parts.length != 3
+
+          payload = JSON.parse(Base64.urlsafe_decode64(jwt_parts[1]))
+          metadata_section = payload.fetch("metadata", {})
+          provider_metadata = metadata_section.fetch("openid_provider", {})
+          entity_jwks = payload.fetch("jwks", {})
+
+          # Combine provider metadata with entity JWKS for encryption
+          # Note: Provider's encryption requirements would be in their discovery document,
+          # but we can also check client metadata as a fallback
+          {
+            "request_object_encryption_alg" => provider_metadata["request_object_encryption_alg"] ||
+              provider_metadata[:request_object_encryption_alg],
+            "request_object_encryption_enc" => provider_metadata["request_object_encryption_enc"] ||
+              provider_metadata[:request_object_encryption_enc],
+            "jwks" => entity_jwks
+          }
+        rescue => e
+          OmniauthOpenidFederation::Logger.debug("[Strategy] Could not load provider metadata for encryption: #{e.message}")
+          nil
+        end
+      end
+    end
+  end
+end