omniauth_openid_federation 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1df7531d0ec2cac4095580f068c1dc7cb09fe53631d87a647b311c05ee9c89f
-  data.tar.gz: 38f06cb5ca370edd986051c4f547b0e53d07d1a61c685cb727c6f2d0e2b34c46
+  metadata.gz: e299269e65c33735c84f2bec3ee0164bc5cb136c8dac5088be188998d826d5bc
+  data.tar.gz: c35464efdf1af7957456641275cfa3a374a1600a0570fa7db7a6ceeb1a31417f
 SHA512:
-  metadata.gz: 81261964b6f0fd468dde2e70b0331e2435129896114b7d4cd087a366596906f160fac90296f856c9055d15e49e51cd8dd8a5ad83d8234b2bec264c49b625b789
-  data.tar.gz: a9d48264edb247c18ce0160fa339f429c3802033e902da6b7c1ef12de5892c44c392415c8ffd57ac6b976190d85a071a199ad3790cc97f0cfe1d4c164d35acba
+  metadata.gz: 9e96511bd8c6972d774435015822297a44892e263b13187ef1a52741186288bf25ded9b15bb0f3c5d856796e7e3b30df9d845c5c3f67987bf7fcd94160c26eda
+  data.tar.gz: 6c5a94f3bb8f429cc9dd583b98032418858520cc93658e9fdba1fe7192d8cb03b9b7e11575d22f44ce5e18cd2cf7bf05f5d512d7a7f96a47404dde00445923e9

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 1.2.0 (2025-11-27)
+
+- Created `OmniauthOpenidFederation::Engine` class inheriting from `Rails::Engine`
+- Engine provides controllers via standard Rails autoloading mechanisms
+- Routes are now defined in Engine's `config/routes.rb` file
+- Routes must now be mounted using `mount OmniauthOpenidFederation::Engine => "/"` in `config/routes.rb`
+- `FederationEndpoint.mount_routes` is still available for backward compatibility
+
 ## 1.1.0 (2025-11-26)
 
 - Enhanced instrumentation: All blocking exceptions automatically reported through instrumentation system, including OmniAuth middleware errors (like AuthenticityTokenProtection)

data/README.md

@@ -178,7 +178,11 @@ OmniauthOpenidFederation::FederationEndpoint.auto_configure(
 
 ```ruby
 # config/routes.rb
-OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+# RECOMMENDED: Mount the Engine (Rails-idiomatic way)
+mount OmniauthOpenidFederation::Engine => "/"
+
+# ALTERNATIVE: Use mount_routes helper (for backward compatibility)
+# OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
 ```
 
 **Key Points**:
@@ -188,27 +192,50 @@ OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
 
 ### Step 6: Add Routes
 
-#### For Devise
+#### Mount the Engine (Required for Federation Endpoints)
+
+The gem provides a Rails Engine that serves the well-known OpenID Federation endpoints. Mount it in your routes:
 
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
+  # Mount the Engine to enable /.well-known/openid-federation endpoint
+  mount OmniauthOpenidFederation::Engine => "/"
+  
+  # Your other routes...
   devise_for :users, controllers: {
     omniauth_callbacks: "users/omniauth_callbacks"
   }
 end
 ```
 
-#### For OmniAuth
+**Note**: The Engine is mounted at root (`"/"`) because OpenID Federation requires endpoints at specific well-known paths (e.g., `/.well-known/openid-federation`). The Engine's routes are defined in the gem and automatically available when mounted.
+
+#### For OmniAuth (Non-Devise)
 
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
+  mount OmniauthOpenidFederation::Engine => "/"
+  
   get "/auth/:provider/callback", to: "sessions#create"
   get "/auth/failure", to: "sessions#failure"
 end
 ```
 
+#### Alternative: Manual Route Mounting (Backward Compatibility)
+
+If you need custom paths or prefer manual route definition, you can use the `mount_routes` helper (deprecated):
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Use mount_routes helper for custom paths (deprecated - prefer Engine mounting)
+  OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+  # ... your other routes
+end
+```
+
 ### Step 7: Configure CSRF Protection
 
 OmniAuth requires CSRF protection configuration to handle both the request phase (initiating OAuth) and callback phase (external provider redirect).
@@ -583,7 +610,11 @@ OmniauthOpenidFederation::FederationEndpoint.auto_configure(
 
 ```ruby
 # config/routes.rb
-OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
+# RECOMMENDED: Mount the Engine (Rails-idiomatic way)
+mount OmniauthOpenidFederation::Engine => "/"
+
+# ALTERNATIVE: Use mount_routes helper (for backward compatibility)
+# OmniauthOpenidFederation::FederationEndpoint.mount_routes(self)
 ```
 
 **What `auto_configure` does automatically**:

data/lib/omniauth_openid_federation/engine.rb

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

data/lib/omniauth_openid_federation/federation_endpoint.rb

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

data/lib/omniauth_openid_federation/railtie.rb

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

data/lib/omniauth_openid_federation/version.rb

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

data/lib/omniauth_openid_federation.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth_openid_federation
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -291,6 +291,7 @@ files:
 - lib/omniauth_openid_federation/configuration.rb
 - lib/omniauth_openid_federation/constants.rb
 - lib/omniauth_openid_federation/endpoint_resolver.rb
+- lib/omniauth_openid_federation/engine.rb
 - lib/omniauth_openid_federation/entity_statement_reader.rb
 - lib/omniauth_openid_federation/errors.rb
 - lib/omniauth_openid_federation/federation/entity_statement.rb