Add stub login for development

[senid231]

Developing against an OIDC-only admin panel is painful: the IdP must know your local redirect URI, which breaks on a different port or when two apps share one client. Projects work around it with per-repo bypass controllers that skip the gem's provisioning path, so authorization is never exercised locally.

Adds one config method:

ActiveAdmin::Oidc.configure do |c|
  c.stub_dev_env_login! do |claims|
    claims.merge("groups" => [ADMIN_GROUP])
  end
end

The login page renders as always — same button, same label — but the button signs in with locally fabricated claims instead of redirecting to the IdP. A red warning sits above it while it is on. The block is optional and runs per sign-in, so it can return a different identity each time.

It is not a separate code path. The button POSTs to the gem's own callbacks controller, which hands the claims to the same UserProvisioner a real callback uses — identity lookup, the takeover guard, your on_login hook, oidc_raw_info and active_for_authentication? all still run. provider stays "oidc", so a stub row is an ordinary OIDC row that a later real SSO login still matches.

Safety is the method itself: stub_dev_env_login! is a no-op outside the development environment and the route is not drawn there. Nothing to flip off before a deploy, no boot guard to trip.

Also fixes the published login view templates, which used generator-escaped <%%= while being copied verbatim — a host that published the view got literal ERB tags rendered as page text.

[Copilot]

Pull request overview

Adds a guarded development-only stub login flow through the existing OIDC provisioning pipeline.

Changes:

• Adds configurable stub claims, UI, routes, callbacks, and production safeguards.
• Updates bundled and generated login templates, documentation, and tests.
• Bumps the version to 2.2.0.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Summary
spec/unit/configuration_spec.rb	Tests stub configuration and validation.
spec/requests/stub_login_spec.rb	Tests stub-login behavior and safeguards.
spec/isolated/features/isolated_stub_login_spec.rb	Tests isolated-engine routing.
spec/generators/install_generator_spec.rb	Tests generated login templates.
README.md	Documents stub-login configuration and usage.
lib/generators/active_admin/oidc/install/templates/sessions_new.html.erb	Updates the generated legacy login view.
lib/generators/active_admin/oidc/install/templates/sessions_new_v4.html.erb	Updates the generated ActiveAdmin 4 login view.
lib/generators/active_admin/oidc/install/templates/initializer.rb.tt	Documents generated stub configuration.
lib/activeadmin/oidc/version.rb	Bumps the version to 2.2.0.
lib/activeadmin/oidc/engine.rb	Registers helpers, guards, and conditional routes.
lib/activeadmin/oidc/configuration.rb	Adds stub settings and claim validation.
app/views/active_admin/devise/sessions/new.html.erb	Adds stub-login UI to the bundled view.
app/helpers/active_admin/oidc/view_helpers.rb	Provides login and route helpers.
app/controllers/active_admin/oidc/devise/omniauth_callbacks_controller.rb	Handles stub provisioning and sign-in.

Suppressed comments (5)

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

• This new stub endpoint calls the shared sign-in tail, whose after_sign_in_path_for falls back to the hardcoded /admin. In the documented isolated-engine setup, the added feature spec already has to avoid following this redirect because /admin is not routed there, so a user who clicks the stub button can be sent to a dead page instead of completing the login flow. Make the post-login destination route-aware for the mounted Devise/ActiveAdmin route set and assert the final location in the isolated integration spec.

          provision_and_sign_in(claims)

app/helpers/active_admin/oidc/view_helpers.rb:54

• Once invalid claims are represented as ConfigurationError, this view helper still lets that exception escape while rendering the login page, because it only handles the normal missing-identity case with presence. A malformed stub_login_claims would therefore make GET /admin/login fail before the user can see the endpoint's configuration flash; rescue the configuration error here and return nil so the existing (unconfigured identity) banner is rendered.

      def activeadmin_oidc_stub_login_identity
        claims = activeadmin_oidc_config.resolved_stub_login_claims
        claims[activeadmin_oidc_config.identity_claim.to_s].presence

lib/activeadmin/oidc/configuration.rb:87

• stub_login_claims is documented as a Hash (or a callable returning one), but a non-Hash value such as a String reaches (raw || {}).to_h and raises NoMethodError. The stub action only translates ConfigurationError, so a malformed configuration produces a 500 instead of the intended readable misconfiguration response. Validate the resolved value's type before calling to_h and raise ConfigurationError for invalid values.

        (raw || {}).to_h.transform_keys(&:to_s)

lib/activeadmin/oidc/configuration.rb:19

• The default stub subject ("stub-uid") will normally differ from the real IdP subject for the same email. UserProvisioner first looks up (provider, uid) and then rejects an identity row that already has any provider/uid, so using the same "oidc" provider does not make the later real login match; it causes the takeover guard to reject it. Either require/configure a stable real subject for the stub, or add an explicit and security-reviewed transition for stub-created rows instead of relying on the provider value alone.

      DEFAULT_STUB_LOGIN_CLAIMS = {
        'sub'   => 'stub-uid',
        'email' => 'stub@example.com'

lib/activeadmin/oidc/engine.rb:159

• enforce_stub_login_policy! only validates the claims here, so enabling stub login with on_login = nil (or another non-callable value) still boots even though Configuration#validate! explicitly requires that hook. The first stub POST then reaches @config.on_login.call and raises NoMethodError/500 instead of failing at boot as the configuration contract implies; run cfg.validate! in this guard before the stub-claims validation.

        cfg.validate_stub_login! unless cfg.stub_login_claims.respond_to?(:call)

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.