TDD step 6: Rails engine + dummy app + OmniAuth wiring

Registers the gem's OmniauthCallbacksController via a singleton_class
prepend on ActiveAdmin::Devise inside a to_prepare callback so the
patch applies after ActionDispatch has set up controller autoloading.
Adds a minimal dummy Rails app under spec/dummy for request specs.

Author: Fivell

Gemfile

@@ -3,3 +3,8 @@
 source "https://rubygems.org"
 
 gemspec
+
+# Pin Rails for the dev/test environment. The gemspec allows >= 7.2 at
+# runtime, but the dummy app and specs are validated against 7.2.
+gem "rails", "~> 7.2.0"
+gem "activerecord", "~> 7.2.0"

activeadmin-oidc.gemspec

@@ -39,6 +39,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "webmock",      ">= 3.19"
   spec.add_development_dependency "jwt",          ">= 2.7"
   spec.add_development_dependency "sqlite3",      ">= 1.7"
+  spec.add_development_dependency "sprockets-rails", ">= 3.4"
+  spec.add_development_dependency "sassc-rails",     ">= 2.1"
   spec.add_development_dependency "rake",         ">= 13.0"
   spec.add_development_dependency "rubocop",      ">= 1.60"
   spec.add_development_dependency "rubocop-rails", ">= 2.20"

app/controllers/active_admin/oidc/devise/omniauth_callbacks_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "devise"
+
+module ActiveAdmin
+  module Oidc
+    module Devise
+      # Handles the OAuth callback from the IdP. Wiring:
+      #
+      #   # config/routes.rb (or inside ActiveAdmin::Devise.config)
+      #   devise_for :admin_users, ActiveAdmin::Devise.config.merge(
+      #     controllers: {
+      #       omniauth_callbacks: "active_admin/oidc/devise/omniauth_callbacks"
+      #     }
+      #   )
+      #
+      # The action name matches the provider name registered with Devise
+      # (`:oidc`, from ActiveAdmin::Oidc::Engine::PROVIDER_NAME).
+      class OmniauthCallbacksController < ::Devise::OmniauthCallbacksController
+        def oidc
+          auth   = request.env["omniauth.auth"] || {}
+          info   = auth["info"] || {}
+          extra  = auth.dig("extra", "raw_info") || {}
+
+          claims = extra.to_h.transform_keys(&:to_s)
+          claims["sub"]   = auth["uid"] if claims["sub"].blank? && auth["uid"].present?
+          claims["email"] = info["email"] if claims["email"].blank? && info["email"].present?
+
+          admin_user = UserProvisioner.new(
+            ActiveAdmin::Oidc.config,
+            claims:   claims,
+            provider: ActiveAdmin::Oidc::Engine::PROVIDER_NAME.to_s
+          ).call
+
+          sign_in_and_redirect admin_user, event: :authentication
+          set_flash_message(:notice, :success, kind: "OIDC") if is_navigational_format?
+        rescue ActiveAdmin::Oidc::ProvisioningError => e
+          Rails.logger.warn("[activeadmin-oidc] denial: #{e.message}")
+          flash[:alert] = ActiveAdmin::Oidc.config.access_denied_message
+          redirect_to after_omniauth_failure_path_for(resource_name)
+        end
+
+        def failure
+          Rails.logger.warn("[activeadmin-oidc] omniauth failure: #{failure_message}")
+          flash[:alert] = ActiveAdmin::Oidc.config.access_denied_message
+          redirect_to after_omniauth_failure_path_for(resource_name)
+        end
+      end
+    end
+  end
+end

lib/activeadmin-oidc.rb

@@ -30,3 +30,14 @@ def reset!
 require "activeadmin/oidc/discovery"
 require "activeadmin/oidc/presets/zitadel"
 require "activeadmin/oidc/user_provisioner"
+require "rails/engine"
+require "activeadmin/oidc/engine"
+require "activeadmin/oidc/omniauth_options"
+
+module ActiveAdmin
+  module Oidc
+    def self.omniauth_options
+      OmniauthOptions.build(config)
+    end
+  end
+end

lib/activeadmin/oidc/engine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module ActiveAdmin
+  module Oidc
+    # Mountable Rails engine. Ships the OmniauthCallbacksController the host
+    # app's Devise setup routes to, and exposes the hardcoded callback path
+    # all hosts share.
+    class Engine < ::Rails::Engine
+      # OmniAuth strategy name. The callback URL in the host app is
+      #   <host>/admin/auth/oidc/callback
+      # (ActiveAdmin mounts Devise under /admin by default.) Zitadel and
+      # other IdPs support multiple redirect URIs per app, so hardcoding
+      # this path keeps config surface small with no real downside.
+      PROVIDER_NAME = :oidc
+
+      # Prepended into ActiveAdmin::Devise's singleton class so that
+      # `ActiveAdmin::Devise.controllers` includes the gem's omniauth
+      # callbacks controller without any host-app wiring.
+      ControllersPatch = Module.new do
+        def controllers
+          super.merge(
+            omniauth_callbacks: "active_admin/oidc/devise/omniauth_callbacks"
+          )
+        end
+      end
+
+      # Apply the patch once ActiveAdmin::Devise is loadable. We use
+      # `to_prepare` rather than a regular initializer because
+      # `active_admin/devise` references `::Devise::SessionsController`
+      # at file load, and that constant isn't autoloadable until
+      # ActionDispatch has set up controller autoload paths — which
+      # only happens after the initializer phase.
+      initializer "activeadmin_oidc.register_controllers" do |app|
+        app.config.to_prepare do
+          require "active_admin/devise"
+          unless ::ActiveAdmin::Devise.singleton_class < ControllersPatch
+            ::ActiveAdmin::Devise.singleton_class.prepend(ControllersPatch)
+          end
+        end
+      end
+    end
+  end
+end

lib/activeadmin/oidc/omniauth_options.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Oidc
+    # Builds the options hash the host app passes to
+    # `Devise.setup { |c| c.omniauth :openid_connect, ... }`. Shape is
+    # determined by the upstream `omniauth_openid_connect` gem.
+    module OmniauthOptions
+      module_function
+
+      def build(config = ActiveAdmin::Oidc.config)
+        config.validate!
+
+        {
+          name:          Engine::PROVIDER_NAME,
+          issuer:        config.issuer,
+          discovery:     true,
+          scope:         config.scope.to_s.split(/\s+/).map(&:to_sym),
+          response_type: :code,
+          pkce:          config.pkce,
+          client_options: {
+            identifier:   config.issuer && config.client_id,
+            secret:       config.client_secret,
+            port:         nil,
+            scheme:       nil,
+            host:         nil
+          }.compact
+        }
+      end
+    end
+  end
+end

spec/dummy/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "config/application"
+Rails.application.load_tasks

spec/dummy/app/admin/dashboard.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+ActiveAdmin.register_page "Dashboard" do
+  menu priority: 1, label: proc { I18n.t("active_admin.dashboard") }
+
+  content title: proc { I18n.t("active_admin.dashboard") } do
+    para "Dummy dashboard."
+  end
+end

spec/dummy/app/assets/config/manifest.js

@@ -0,0 +1 @@
+// no assets needed for the dummy app

spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationController < ActionController::Base
+end