activeadmin-oidc 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5aaac0eb113550e4278c0ebd3dcae2898c148d2f439a87da8c119ed9a5129811
+  data.tar.gz: ee952618ae8ad48518d4f6a125b20a5e4ccaf3840233391e98964f11a708f222
+SHA512:
+  metadata.gz: dbf926e94596cadb0d98a934ccd75dfa82f5ca3f2c97f9db665bfb0e3ef2bada39256620bc9078127e3cd36fc6dbf750dc0cbfc3de3f8d5cfc38ba2f40bb6cee
+  data.tar.gz: 45f36af5f4986bb57a539e93b9efbedd8e27e2402d5848b770891e1cac8e32d9013b57da143b9f30802b440a724e36e7839a4a395b14c46d2a0d150a3cc0646c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Fedoronchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,272 @@
+# activeadmin-oidc
+
+[![CI](https://github.com/activeadmin-plugins/activeadmin-oidc/actions/workflows/ci.yml/badge.svg)](https://github.com/activeadmin-plugins/activeadmin-oidc/actions/workflows/ci.yml)
+
+OpenID Connect single sign-on for [ActiveAdmin](https://activeadmin.info/).
+
+Plugs OIDC into ActiveAdmin's existing Devise stack: JIT user provisioning, an `on_login` hook for host-owned authorization, a login-button view override, and a one-shot install generator. The OIDC protocol layer (discovery, JWKS, token verification, PKCE, nonce, state) is delegated to [`omniauth_openid_connect`](https://github.com/omniauth/omniauth_openid_connect).
+
+Used in production by the authors against [Zitadel](https://zitadel.com/). Other compliant OIDC providers work via the standard omniauth_openid_connect options.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "activeadmin-oidc"
+```
+
+```sh
+bundle install
+bin/rails generate active_admin:oidc:install
+bin/rails db:migrate
+```
+
+## Host-app setup checklist
+
+The generator creates the initializer and migration, but it cannot edit your `active_admin.rb` or `admin_user.rb`. Three things have to be in place:
+
+### 1. `config/initializers/active_admin.rb`
+
+```ruby
+config.authentication_method = :authenticate_admin_user!
+config.current_user_method   = :current_admin_user
+```
+
+Without these, `/admin` is public to anyone and the utility navigation (including the logout button) renders empty.
+
+### 2. `app/models/admin_user.rb`
+
+```ruby
+class AdminUser < ApplicationRecord
+  devise :database_authenticatable,
+         :rememberable,
+         :omniauthable, omniauth_providers: [:oidc]
+
+  serialize :oidc_raw_info, coder: JSON
+end
+```
+
+### 3. `config/initializers/activeadmin_oidc.rb` (generated)
+
+Fill in at minimum `issuer`, `client_id`, and an `on_login` hook. Full reference below.
+
+## What the engine does automatically
+
+The gem's Rails engine handles several things so host apps don't have to:
+
+* **OmniAuth strategy registration** — the engine registers the `:openid_connect` strategy with Devise automatically based on your `ActiveAdmin::Oidc` configuration. You do **not** need to add `config.omniauth` or `config.omniauth_path_prefix` to `devise.rb`.
+* **Callback controller** — the engine patches `ActiveAdmin::Devise.controllers` to route OmniAuth callbacks to the gem's controller. No manual `controllers: { omniauth_callbacks: ... }` needed in `routes.rb`.
+* **Login view override** — the engine prepends an SSO-only login page (no email/password fields) to the sessions controller's view path. If your host app ships its own `app/views/active_admin/devise/sessions/new.html.erb`, the gem detects it and backs off — your view wins.
+* **Path prefix** — the engine sets `Devise.omniauth_path_prefix` and `OmniAuth.config.path_prefix` to `/admin/auth` so the middleware intercepts requests under ActiveAdmin's mount point. Compatible with Rails 7.2+ and Rails 8's lazy route loading.
+* **Parameter filtering** — `code`, `id_token`, `access_token`, `refresh_token`, `state`, and `nonce` are added to `Rails.application.config.filter_parameters`.
+
+## Configuration
+
+```ruby
+ActiveAdmin::Oidc.configure do |c|
+  # --- Provider endpoints -----------------------------------------------
+  c.issuer        = ENV.fetch("OIDC_ISSUER")
+  c.client_id     = ENV.fetch("OIDC_CLIENT_ID")
+  c.client_secret = ENV.fetch("OIDC_CLIENT_SECRET", nil) # blank ⇒ PKCE public client
+
+  # --- OIDC scopes ------------------------------------------------------
+  # c.scope = "openid email profile"
+
+  # --- Redirect URI -----------------------------------------------------
+  # Normally auto-derived from the callback route. Set explicitly when
+  # behind a reverse proxy, CDN, or when the IdP requires exact matching.
+  # c.redirect_uri = "https://admin.example.com/admin/auth/oidc/callback"
+
+  # --- Identity lookup --------------------------------------------------
+  # Which AdminUser column to match existing rows against, and which
+  # claim on the id_token/userinfo to read for the lookup.
+  # c.identity_attribute = :email
+  # c.identity_claim     = :email
+
+  # --- AdminUser model resolution ---------------------------------------
+  # Accepts a String (lazy constant lookup, recommended) or a Class.
+  # Use when your model is not literally ::AdminUser.
+  # c.admin_user_class = "Admin::User"
+
+  # --- UI copy ----------------------------------------------------------
+  # c.login_button_label    = "Sign in with Corporate SSO"
+  # c.access_denied_message = "Your account has no permission to access this admin panel."
+
+  # --- PKCE override ----------------------------------------------------
+  # By default PKCE is enabled iff client_secret is blank. Override:
+  # c.pkce = true
+
+  # --- Authorization hook (REQUIRED) ------------------------------------
+  c.on_login = ->(admin_user, claims) {
+    # ... see "The on_login hook" below
+    true
+  }
+end
+```
+
+### Option reference
+
+| Option | Default | Purpose |
+|---|---|---|
+| `issuer` | — (required) | OIDC discovery base URL |
+| `client_id` | — (required) | IdP client identifier |
+| `client_secret` | `nil` | Blank ⇒ PKCE public client |
+| `scope` | `"openid email profile"` | Space-separated OIDC scopes |
+| `pkce` | auto | `true` when `client_secret` is blank; overridable |
+| `redirect_uri` | `nil` (auto) | Explicit callback URL; needed behind reverse proxies |
+| `identity_attribute` | `:email` | AdminUser column used for lookup/adoption |
+| `identity_claim` | `:email` | Claim key read from the id_token/userinfo |
+| `admin_user_class` | `"AdminUser"` | String or Class for the host's admin user model |
+| `login_button_label` | `"Sign in with SSO"` | Label on the login-page button |
+| `access_denied_message` | generic | Flash shown on any denial |
+| `on_login` | — (required) | Authorization hook; see below |
+
+## The `on_login` hook
+
+`on_login` is the **only** place authorization lives. The gem handles authentication (the user proved who they are via the IdP); deciding whether that user is allowed into the admin panel — and what they can see once they are in — is the host application's problem. The gem does not ship a role model.
+
+### Signature
+
+```ruby
+c.on_login = ->(admin_user, claims) {
+  # admin_user: an instance of the configured admin_user_class.
+  #             Either a pre-existing row (matched by provider/uid or by
+  #             identity_attribute) or an unsaved new record.
+  # claims:     a Hash of String keys. Contains everything the IdP
+  #             returned in the id_token/userinfo, plus the top-level
+  #             `sub` (copied from the OmniAuth uid) and `email`
+  #             (copied from info.email) for convenience.
+  #             access_token / refresh_token / id_token are NEVER
+  #             present — they are stripped before this hook runs.
+  #
+  # Return truthy to allow sign-in.
+  # Return falsy (false/nil) to deny: the user sees a generic denial
+  # flash and no AdminUser record is persisted or mutated.
+  #
+  # Any mutations you make to admin_user are persisted automatically
+  # after the hook returns truthy.
+  #
+  # Exceptions raised inside the hook are logged at :error via
+  # ActiveAdmin::Oidc.logger and surface to the user as the same
+  # generic denial flash — the callback action never 500s.
+  true
+}
+```
+
+### Example A — Zitadel nested project roles claim
+
+Zitadel emits roles under the custom claim `urn:zitadel:iam:org:project:roles`, shaped as `{ "role-name" => { "org-id" => "org-name" } }`. Flatten the keys into a string array on the AdminUser.
+
+```ruby
+c.on_login = ->(admin_user, claims) {
+  roles = claims["urn:zitadel:iam:org:project:roles"]&.keys || []
+  return false if roles.empty?
+
+  admin_user.roles = roles
+  admin_user.name  = claims["name"] if claims["name"].present?
+  true
+}
+```
+
+### Example B — department-based gating
+
+```ruby
+KNOWN_DEPARTMENTS = %w[ops eng support].freeze
+
+c.on_login = ->(admin_user, claims) {
+  dept = claims["department"]
+  return false unless KNOWN_DEPARTMENTS.include?(dept)
+
+  admin_user.department = dept
+  true
+}
+```
+
+### Example C — syncing from a standard `groups` claim (Keycloak-style)
+
+```ruby
+ADMIN_GROUP = "admins"
+
+c.on_login = ->(admin_user, claims) {
+  groups = Array(claims["groups"])
+  return false unless groups.include?(ADMIN_GROUP)
+
+  admin_user.super_admin = groups.include?("super-admins")
+  true
+}
+```
+
+## Reading additional claims from the callback
+
+Every key the IdP returns in the id_token or userinfo is passed to `on_login` as part of `claims`. Custom claims work the same as standard ones — just read them by key:
+
+```ruby
+c.on_login = ->(admin_user, claims) {
+  admin_user.employee_id    = claims["employee_id"]
+  admin_user.given_name     = claims["given_name"]
+  admin_user.family_name    = claims["family_name"]
+  admin_user.locale         = claims["locale"]
+  admin_user.email_verified = claims["email_verified"]
+  # Nested / structured claims come through as whatever the IdP sent.
+  # Zitadel metadata, for instance:
+  admin_user.tenant_id      = claims.dig("urn:zitadel:iam:user:metadata", "tenant_id")
+  true
+}
+```
+
+The full claim hash (minus `access_token` / `refresh_token` / `id_token`) is also stored on the admin user as `oidc_raw_info` — a JSON column created by the install generator. Read it later outside the hook for debugging or for showing the user's profile from the IdP:
+
+```ruby
+AdminUser.last.oidc_raw_info
+# => { "sub" => "...", "email" => "...", "groups" => [...], ... }
+```
+
+## Sign-in flow
+
+* A login button is added to the ActiveAdmin sessions page via a prepended view override — no templates to edit.
+* Clicking it POSTs to `/admin/auth/oidc` with a Rails CSRF token. The gem loads `omniauth-rails_csrf_protection` so OmniAuth 2.x delegates its authenticity check to Rails' forgery protection and `button_to` just works.
+* After a successful callback the user is signed in and redirected to `/admin` (not the host app's `/`, which may not exist).
+* **Disabled/locked users are rejected.** Devise's `active_for_authentication?` is checked after provisioning but before sign-in. If your model overrides this method (e.g. to check an `enabled` flag or Devise's `:lockable` module), the guard fires on OIDC sign-in too — the user sees an appropriate flash and is redirected to the login page.
+* Logout goes through Devise's stock session destroy. No RP-initiated single-logout ping to the IdP — override the destroy action in your host app if you need that.
+
+## Custom login view
+
+The gem ships a minimal SSO-only login page (a single button, no email/password fields). If you need a different layout — for instance, a combined SSO + password form for a break-glass mode — drop your own template at:
+
+```
+app/views/active_admin/devise/sessions/new.html.erb
+```
+
+The engine detects the host-app file and does not prepend its own view, so yours takes precedence with no extra configuration.
+
+## Security notes
+
+### Choice of `identity_attribute`
+
+The `identity_attribute` column is used to adopt existing AdminUser rows on first SSO login — an existing user with that value in that column, and no `provider`/`uid` yet, gets linked to the IdP identity. **Do not** point this at a column the IdP can influence and that is also security-sensitive. Safe choices: `:email`, `:username`, `:employee_id`. Unsafe choices: `:admin`, `:super_admin`, `:password_digest`, `:roles` — anything whose value encodes a permission.
+
+### Unique index on the identity column
+
+To prevent concurrent first-logins from creating two AdminUser rows for the same person, the column used as `identity_attribute` should have a database-level unique index. For the default `:email` case the standard Devise migration already adds this. If you pick a custom attribute, add the index yourself:
+
+```ruby
+add_index :admin_users, :employee_id, unique: true
+```
+
+The gem also adds a unique `(provider, uid)` partial index in its own install migration.
+
+### What's filtered from logs
+
+The engine merges `code`, `id_token`, `access_token`, `refresh_token`, `state`, and `nonce` into `Rails.application.config.filter_parameters` so a mid-callback crash can't dump them into production logs. Your own `filter_parameters` entries are preserved.
+
+## Logger
+
+The gem logs internal diagnostics (on_login exceptions, omniauth failures) via `ActiveAdmin::Oidc.logger`. It defaults to `Rails.logger` when Rails is booted, falling back to a null logger otherwise. Override by assigning directly:
+
+```ruby
+ActiveAdmin::Oidc.logger = MyStructuredLogger.new
+```
+
+## License
+
+MIT — see [`LICENSE.txt`](LICENSE.txt).

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

@@ -0,0 +1,79 @@
+# 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'] || {}
+          # Defensive: an OIDC strategy is supposed to put a Hash at
+          # extra.raw_info, but a misbehaving/custom strategy could
+          # set something else (String, nil, Array). We only trust a
+          # Hash-shaped value; anything else collapses to {} and we
+          # rebuild `sub`/`email` from the top-level auth hash below.
+          extra = auth.dig('extra', 'raw_info')
+          extra = {} unless extra.is_a?(Hash)
+
+          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
+
+          # Devise checks active_for_authentication? on session
+          # deserialization but NOT on initial OmniAuth sign-in.
+          # Guard here so disabled/locked users are rejected immediately.
+          unless admin_user.active_for_authentication?
+            message = admin_user.inactive_message
+            flash[:alert] = I18n.t("devise.failure.#{message}", default: message.to_s)
+            redirect_to after_omniauth_failure_path_for(resource_name)
+            return
+          end
+
+          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
+
+        private
+
+        # Land on the ActiveAdmin namespace root after a successful SSO
+        # sign-in instead of Devise's default (host app root). Hosts
+        # that don't define a `/` route would otherwise hit a routing
+        # error immediately after login, and even when `/` does exist
+        # it's rarely what an admin user wants to see. ActiveAdmin
+        # always mounts at `/admin`, so we go there directly.
+        def after_sign_in_path_for(resource)
+          stored_location_for(resource) || '/admin'
+        end
+      end
+    end
+  end
+end

data/app/views/active_admin/devise/sessions/new.html.erb

@@ -0,0 +1,7 @@
+<div id="login">
+  <h2><%= active_admin_application.site_title(self) %></h2>
+
+  <%= form_tag omniauth_authorize_path(resource_name, :oidc), method: :post, data: { turbo: false } do %>
+    <%= submit_tag ActiveAdmin::Oidc.config.login_button_label %>
+  <% end %>
+</div>

data/lib/activeadmin/oidc/configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Oidc
+    class Configuration
+      DEFAULT_SCOPE               = 'openid email profile'
+      DEFAULT_TIMEOUT             = 5
+      DEFAULT_IDENTITY_ATTRIBUTE  = :email
+      DEFAULT_IDENTITY_CLAIM      = :email
+      DEFAULT_LOGIN_BUTTON_LABEL  = 'Sign in with SSO'
+      DEFAULT_ADMIN_USER_CLASS    = 'AdminUser'
+      DEFAULT_ACCESS_DENIED_MESSAGE =
+        'Your account has no permission to access this admin panel.'
+
+      attr_accessor :issuer, :client_id, :client_secret, :scope,
+                    :redirect_uri,
+                    :login_button_label, :timeout,
+                    :identity_attribute, :identity_claim,
+                    :access_denied_message, :on_login, :admin_user_class
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @issuer                = nil
+        @client_id             = nil
+        @client_secret         = nil
+        @scope                 = DEFAULT_SCOPE
+        @redirect_uri          = nil
+        @login_button_label    = DEFAULT_LOGIN_BUTTON_LABEL
+        @timeout               = DEFAULT_TIMEOUT
+        @identity_attribute    = DEFAULT_IDENTITY_ATTRIBUTE
+        @identity_claim        = DEFAULT_IDENTITY_CLAIM
+        @access_denied_message = DEFAULT_ACCESS_DENIED_MESSAGE
+        @admin_user_class      = DEFAULT_ADMIN_USER_CLASS
+        @on_login              = nil
+        @pkce_override         = nil
+        self
+      end
+
+      def pkce
+        return @pkce_override unless @pkce_override.nil?
+
+        client_secret.nil? || client_secret.to_s.empty?
+      end
+
+      def pkce=(value)
+        @pkce_override = value
+      end
+
+      def validate!
+        raise ConfigurationError, 'issuer is required'    if issuer.blank?
+        raise ConfigurationError, 'client_id is required' if client_id.blank?
+        raise ConfigurationError, 'on_login is required'  if on_login.nil?
+        raise ConfigurationError, 'on_login must be callable (respond to #call)' unless on_login.respond_to?(:call)
+
+        true
+      end
+    end
+  end
+end

data/lib/activeadmin/oidc/engine.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module ActiveAdmin
+  module Oidc
+    class Engine < ::Rails::Engine
+      PROVIDER_NAME = :oidc
+
+      # True when the host's AdminUser model includes :omniauthable.
+      # Used to gate controller registration and view overrides so the
+      # gem is a no-op when OIDC is not enabled on the model.
+      def self.oidc_enabled?
+        admin_class = ActiveAdmin::Oidc.config.admin_user_class
+        klass = admin_class.is_a?(String) ? admin_class.safe_constantize : admin_class
+        klass.respond_to?(:devise_modules) && klass.devise_modules.include?(:omniauthable)
+      end
+
+      ControllersPatch = Module.new do
+        def controllers
+          result = super
+          if Engine.oidc_enabled?
+            result = result.merge(
+              omniauth_callbacks: 'active_admin/oidc/devise/omniauth_callbacks'
+            )
+          end
+          result
+        end
+      end
+
+      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
+
+      initializer 'activeadmin_oidc.prepend_view_paths' do |app|
+        app.config.to_prepare do
+          if Engine.oidc_enabled?
+            require 'active_admin/devise'
+            # Only prepend the gem's SSO-only login view if the host app
+            # doesn't ship its own override. This avoids the need for hosts
+            # to re-prepend their views after the gem.
+            host_view = ::Rails.root.join(
+              'app/views/active_admin/devise/sessions/new.html.erb'
+            )
+            unless host_view.exist?
+              view_path = File.expand_path('../../../app/views', __dir__)
+              ::ActiveAdmin::Devise::SessionsController.prepend_view_path(view_path)
+            end
+          end
+        end
+      end
+
+      # Automatically register the OmniAuth :openid_connect strategy with
+      # Devise when the gem is configured, so host apps don't have to
+      # duplicate the config.omniauth boilerplate in devise.rb.
+      # Runs before Devise's own initializer so the strategy is available
+      # when the model calls `devise :omniauthable`.
+      initializer 'activeadmin_oidc.register_omniauth_strategy', before: 'devise.omniauth' do
+        cfg = ActiveAdmin::Oidc.config
+        next if cfg.issuer.blank? || cfg.client_id.blank?
+
+        require 'omniauth_openid_connect'
+
+        ::Devise.setup do |devise|
+          # ActiveAdmin mounts Devise under /admin, so OmniAuth middleware
+          # must intercept /admin/auth/:provider.
+          devise.omniauth_path_prefix ||= '/admin/auth'
+
+          devise.omniauth :openid_connect,
+                          name: PROVIDER_NAME,
+                          scope: (cfg.scope || 'openid email profile').split,
+                          response_type: :code,
+                          issuer: cfg.issuer,
+                          discovery: true,
+                          pkce: cfg.pkce,
+                          client_options: {
+                            identifier: cfg.client_id,
+                            secret: cfg.client_secret.presence,
+                            redirect_uri: cfg.redirect_uri,
+                            port: nil,
+                            scheme: nil,
+                            host: nil
+                          }.compact
+        end
+
+        # Devise propagates omniauth_path_prefix to
+        # OmniAuth.config.path_prefix during route generation
+        # (set_omniauth_path_prefix!). On Rails 8 routes load lazily,
+        # so the OmniAuth middleware may process requests before routes
+        # are drawn and miss the prefix. Set it eagerly here.
+        # Must happen AFTER `devise.omniauth` because that call
+        # triggers autoload of devise/omniauth which nils the value.
+        ::OmniAuth.config.path_prefix = ::Devise.omniauth_path_prefix
+      end
+
+      initializer 'activeadmin_oidc.filter_parameters' do |app|
+        app.config.filter_parameters |= %i[code id_token access_token refresh_token state nonce]
+      end
+    end
+  end
+end

data/lib/activeadmin/oidc/test_helpers.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'omniauth'
+
+module ActiveAdmin
+  module Oidc
+    # Test helpers for host apps. Include in your RSpec config:
+    #
+    #   require "activeadmin/oidc/test_helpers"
+    #
+    #   RSpec.configure do |config|
+    #     config.include ActiveAdmin::Oidc::TestHelpers, oidc_mode: true
+    #     config.after(:each, :oidc_mode) { reset_oidc_stubs }
+    #   end
+    #
+    # Then in specs tagged `oidc_mode: true`:
+    #
+    #   before { stub_oidc_sign_in(sub: "alice-sub", claims: { "email" => "a@b" }) }
+    #
+    module TestHelpers
+      DEFAULT_CLAIMS = {
+        'preferred_username' => 'alice',
+        'email' => 'alice@test',
+        'roles' => ['admin']
+      }.freeze
+
+      # Stubs OmniAuth to return a successful OIDC auth hash.
+      # Merges the given claims with DEFAULT_CLAIMS.
+      def stub_oidc_sign_in(sub: 'alice-sub', claims: {})
+        merged = DEFAULT_CLAIMS.merge(claims.transform_keys(&:to_s))
+        OmniAuth.config.test_mode = true
+        # OmniAuth 2.x still runs request_validation_phase in test mode
+        # (mock_request_call, line 325 of strategy.rb). Disable it so
+        # the CSRF check from omniauth-rails_csrf_protection doesn't
+        # reject the mocked request.
+        @_oidc_saved_request_validation_phase = OmniAuth.config.request_validation_phase
+        OmniAuth.config.request_validation_phase = nil
+        OmniAuth.config.mock_auth[:oidc] = OmniAuth::AuthHash.new(
+          provider: 'oidc',
+          uid: sub,
+          info: {
+            email: merged['email'],
+            name: merged['name'],
+            nickname: merged['preferred_username']
+          },
+          credentials: {},
+          extra: { raw_info: merged.merge('sub' => sub) }
+        )
+      end
+
+      # Stubs OmniAuth to simulate a strategy failure.
+      def stub_oidc_failure(message_key = :invalid_credentials)
+        OmniAuth.config.test_mode = true
+        @_oidc_saved_request_validation_phase = OmniAuth.config.request_validation_phase
+        OmniAuth.config.request_validation_phase = nil
+        OmniAuth.config.mock_auth[:oidc] = message_key
+      end
+
+      # Resets OmniAuth test mode. Call in an `after` hook.
+      def reset_oidc_stubs
+        OmniAuth.config.mock_auth[:oidc] = nil
+        OmniAuth.config.test_mode = false
+        OmniAuth.config.request_validation_phase = @_oidc_saved_request_validation_phase if defined?(@_oidc_saved_request_validation_phase)
+      end
+    end
+
+    # RSpec support for oidc_mode tag filtering.
+    # Require this file in spec_helper or rails_helper to auto-configure:
+    #
+    #   require "activeadmin/oidc/test_helpers"
+    #
+    # Specs tagged `oidc_mode: true` will be skipped unless the AdminUser
+    # model has :omniauthable loaded. Set CI_RUN_OIDC=true in your CI job
+    # to run only OIDC-tagged specs.
+    module RSpecSupport
+      def self.install!
+        return unless defined?(RSpec)
+
+        RSpec.configure do |config|
+          config.include TestHelpers, oidc_mode: true
+          config.after(:each, :oidc_mode) { reset_oidc_stubs }
+
+          config.before(:each, :oidc_mode) do
+            admin_class = ActiveAdmin::Oidc.config.admin_user_class
+            klass = admin_class.is_a?(String) ? admin_class.safe_constantize : admin_class
+            unless klass.respond_to?(:devise_modules) && klass.devise_modules.include?(:omniauthable)
+              skip 'requires OIDC mode (run with config/oidc.yml in place and CI_RUN_OIDC=true)'
+            end
+          end
+
+          if ENV['CI_RUN_OIDC'].present?
+            config.filter_run_including oidc_mode: true
+          else
+            config.filter_run_excluding oidc_mode: true
+          end
+        end
+      end
+    end
+  end
+end
+
+# Auto-install RSpec support when required during a test run.
+ActiveAdmin::Oidc::RSpecSupport.install!