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.
@@ -101,21 +108,22 @@ end
 
 | Option | Default | Purpose |
 |---|---|---|
-| `issuer` | — (required) | OIDC discovery base URL |
-| `client_id` | — (required) | IdP client identifier |
-| `client_secret` | `nil` | Blank ⇒ PKCE public client |
+| `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 |
+| `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.
+`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
 
@@ -129,7 +137,7 @@ c.on_login = ->(admin_user, claims) {
   #             `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.
+  #             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
@@ -140,12 +148,12 @@ c.on_login = ->(admin_user, claims) {
   #
   # 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.
+  # generic denial flash -- the callback action never 500s.
   true
 }
 ```
 
-### Example A — Zitadel nested project roles claim
+### 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.
 
@@ -160,7 +168,7 @@ c.on_login = ->(admin_user, claims) {
 }
 ```
 
-### Example B — department-based gating
+### Example B -- department-based gating
 
 ```ruby
 KNOWN_DEPARTMENTS = %w[ops eng support].freeze
@@ -174,7 +182,7 @@ c.on_login = ->(admin_user, claims) {
 }
 ```
 
-### Example C — syncing from a standard `groups` claim (Keycloak-style)
+### Example C -- syncing from a standard `groups` claim (Keycloak-style)
 
 ```ruby
 ADMIN_GROUP = "admins"
@@ -190,7 +198,7 @@ c.on_login = ->(admin_user, claims) {
 
 ## 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:
+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) {
@@ -206,7 +214,7 @@ c.on_login = ->(admin_user, claims) {
 }
 ```
 
-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:
+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
@@ -215,16 +223,92 @@ AdminUser.last.oidc_raw_info
 
 ## Sign-in flow
 
-* A login button is added to the ActiveAdmin sessions page via a prepended view override — no templates to edit.
+* 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).
-* 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.
+* **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`
 
-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.
+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
 
@@ -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
 
@@ -250,4 +334,4 @@ ActiveAdmin::Oidc.logger = MyStructuredLogger.new
 
 ## License
 
-MIT — see [`LICENSE.txt`](LICENSE.txt).
+MIT -- see [`LICENSE.txt`](LICENSE.txt).