Update README: document auto-registration, test helpers, active_for_authentication guard, redirect_uri, custom views

- Remove outdated devise.rb manual setup step (engine handles it)
- Add 'What the engine does automatically' section
- Add redirect_uri to config example and option table
- Document active_for_authentication? guard in sign-in flow
- Add 'Custom login view' section (host views take precedence)
- Add 'Testing' section with test helpers, CI job pattern
- Reduce setup checklist from 4 items to 3

Author: Fivell

README.md

@@ -23,7 +23,7 @@ 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`. Four things have to be in place:
+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`
 
@@ -46,17 +46,19 @@ class AdminUser < ApplicationRecord
 end
 ```
 
-### 3. `config/initializers/devise.rb`
+### 3. `config/initializers/activeadmin_oidc.rb` (generated)
 
-ActiveAdmin mounts Devise under `/admin`, so OmniAuth's path prefix has to match:
+Fill in at minimum `issuer`, `client_id`, and an `on_login` hook. Full reference below.
 
-```ruby
-config.omniauth_path_prefix = "/admin/auth"
-```
+## What the engine does automatically
 
-### 4. `config/initializers/activeadmin_oidc.rb` (generated)
+The gem's Rails engine handles several things so host apps don't have to:
 
-Fill in at minimum `issuer`, `client_id`, and an `on_login` hook. Full reference below.
+* **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
 
@@ -70,6 +72,11 @@ ActiveAdmin::Oidc.configure do |c|
   # --- 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.
@@ -106,6 +113,7 @@ end
 | `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 |
@@ -218,8 +226,84 @@ AdminUser.last.oidc_raw_info
 * 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.
+
+## Testing
+
+The gem ships test helpers for host apps that need to exercise OIDC sign-in flows in their own specs.
+
+### Quick setup
+
+```ruby
+# spec/rails_helper.rb (or spec/support/oidc.rb)
+require "activeadmin/oidc/test_helpers"
+```
+
+This single `require` auto-configures RSpec:
+
+* Includes `ActiveAdmin::Oidc::TestHelpers` in specs tagged `oidc_mode: true`
+* Resets OmniAuth mocks after each `oidc_mode` example
+* Skips `oidc_mode` specs when the AdminUser model doesn't have `:omniauthable` loaded (i.e. when OIDC is not the active auth backend)
+* When `CI_RUN_OIDC=true` is set, runs **only** `oidc_mode` specs (useful for a dedicated CI job)
+
+### Available helpers
+
+```ruby
+RSpec.describe "OIDC sign-in", type: :feature, oidc_mode: true do
+  it "provisions a new user" do
+    # Stubs OmniAuth to return a successful OIDC auth hash.
+    # Merges given claims with sensible defaults (preferred_username, email, roles).
+    stub_oidc_sign_in(sub: "alice-sub", claims: { "email" => "alice@example.com" })
+
+    visit new_admin_user_session_path
+    click_button "Sign in with SSO"
+
+    expect(page).to have_current_path("/admin")
+  end
+
+  it "handles IdP errors" do
+    # Stubs OmniAuth to simulate a strategy failure.
+    stub_oidc_failure(:invalid_credentials)
+
+    visit new_admin_user_session_path
+    click_button "Sign in with SSO"
+
+    expect(page).to have_content("no permission")
+  end
+end
+```
+
+| Helper | Purpose |
+|---|---|
+| `stub_oidc_sign_in(sub:, claims: {})` | Mock a successful OIDC callback with the given `sub` and claims |
+| `stub_oidc_failure(message_key)` | Mock an OmniAuth strategy failure (e.g. `:invalid_credentials`) |
+| `reset_oidc_stubs` | Clear mocks and disable test mode (called automatically in `after`) |
+
+### CI job pattern
+
+For apps that support multiple auth backends (DB, LDAP, OIDC) selected at boot time, run OIDC specs in a separate CI job:
+
+```yaml
+oidc-specs:
+  steps:
+    - run: cp config/oidc.yml.distr config/oidc.yml
+    - run: bundle exec rails db:create db:migrate
+    - run: CI_RUN_OIDC=true bundle exec rspec --tag oidc_mode
+```
+
+The default job should exclude them: `bundle exec rspec --tag ~oidc_mode`.
+
 ## Security notes
 
 ### Choice of `identity_attribute`
@@ -238,7 +322,7 @@ The gem also adds a unique `(provider, uid)` partial index in its own install mi
 
 ### What's filtered from logs
 
-The initializer 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.
+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