TDD steps 1-5: Configuration, Discovery, Zitadel preset, UserProvisioner

Implements the unit-test layer of the test plan, in red-green-refactor
order. 72 examples, 0 failures.

- Configuration: defaults, validate!, pkce auto-on when client_secret
  blank, preset loader. No callback_path config (hardcoded on engine).
- Discovery: own HTTP fetch with DiscoveryError on 5xx / malformed JSON /
  timeout / issuer-mismatch. Memoized, supports per-endpoint override.
- Presets::Zitadel: two-line preset (scope default + pkce-if-no-secret).
  No role parsing here; that moves to the host on_login hook.
- UserProvisioner: lookup by (provider, uid), then identity-attribute
  migration, then new record, then on_login hook, then save. Denial
  raises ProvisioningError with config.access_denied_message; existing
  records are never mutated on denial. oidc_raw_info strips tokens.

Also rewrites docs/TEST_PLAN.md around the "no gem-owned authorization
model" design: the host app owns all role / permission / department
columns and assigns them inside a single on_login(admin_user, claims)
lambda. Added section 12 "Design rationale" explaining why.

Author: Fivell

docs/TEST_PLAN.md

@@ -8,5 +8,25 @@ class Error < StandardError; end
     class ConfigurationError < Error; end
     class DiscoveryError < Error; end
     class ProvisioningError < Error; end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        config
+      end
+
+      def reset!
+        @config = Configuration.new
+      end
+    end
   end
 end
+
+require "activeadmin/oidc/configuration"
+require "activeadmin/oidc/discovery"
+require "activeadmin/oidc/presets/zitadel"
+require "activeadmin/oidc/user_provisioner"

lib/activeadmin-oidc.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Oidc
+    class Configuration
+      DEFAULT_SCOPE               = "openid email profile"
+      DEFAULT_CLOCK_SKEW          = 30
+      DEFAULT_TIMEOUT             = 5
+      DEFAULT_IDENTITY_ATTRIBUTE  = :email
+      DEFAULT_IDENTITY_CLAIM      = :email
+      DEFAULT_LOGIN_BUTTON_LABEL  = "Sign in with SSO"
+      DEFAULT_ACCESS_DENIED_MESSAGE =
+        "Your account has no permission to access this admin panel."
+
+      attr_accessor :issuer, :client_id, :client_secret, :scope,
+                    :login_button_label, :clock_skew, :timeout,
+                    :identity_attribute, :identity_claim,
+                    :access_denied_message, :on_login
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @issuer                = nil
+        @client_id             = nil
+        @client_secret         = nil
+        @scope                 = DEFAULT_SCOPE
+        @login_button_label    = DEFAULT_LOGIN_BUTTON_LABEL
+        @clock_skew            = DEFAULT_CLOCK_SKEW
+        @timeout               = DEFAULT_TIMEOUT
+        @identity_attribute    = DEFAULT_IDENTITY_ATTRIBUTE
+        @identity_claim        = DEFAULT_IDENTITY_CLAIM
+        @access_denied_message = DEFAULT_ACCESS_DENIED_MESSAGE
+        @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 preset(name)
+        case name
+        when :zitadel
+          require "activeadmin/oidc/presets/zitadel"
+          Presets::Zitadel.apply(self)
+        else
+          raise ConfigurationError, "Unknown preset: #{name.inspect}"
+        end
+      end
+
+      def validate!
+        raise ConfigurationError, "issuer is required"    if blank?(issuer)
+        raise ConfigurationError, "client_id is required" if blank?(client_id)
+        raise ConfigurationError, "on_login is required"  if on_login.nil?
+        unless on_login.respond_to?(:call)
+          raise ConfigurationError, "on_login must be callable (respond to #call)"
+        end
+
+        true
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

lib/activeadmin/oidc/configuration.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module ActiveAdmin
+  module Oidc
+    # Thin wrapper around the OIDC discovery document
+    # (`.well-known/openid-configuration`). Does its own HTTP fetch so the
+    # gem can expose a normalized interface and error type independent of
+    # `omniauth_openid_connect`'s internals.
+    class Discovery
+      DISCOVERY_PATH = "/.well-known/openid-configuration"
+
+      def initialize(config)
+        @config = config
+      end
+
+      def document
+        @document ||= fetch_and_validate!
+      end
+
+      def authorization_endpoint(override: nil)
+        override || document.fetch("authorization_endpoint")
+      end
+
+      def token_endpoint(override: nil)
+        override || document.fetch("token_endpoint")
+      end
+
+      def userinfo_endpoint(override: nil)
+        override || document.fetch("userinfo_endpoint")
+      end
+
+      def jwks_uri(override: nil)
+        override || document.fetch("jwks_uri")
+      end
+
+      def end_session_endpoint(override: nil)
+        override || document["end_session_endpoint"]
+      end
+
+      def issuer
+        document.fetch("issuer")
+      end
+
+      private
+
+      attr_reader :config
+
+      def fetch_and_validate!
+        body = fetch_body
+        doc  = parse_json(body)
+        verify_issuer!(doc)
+        doc
+      end
+
+      def fetch_body
+        uri = URI.join(ensure_trailing_slash(config.issuer), DISCOVERY_PATH.sub(%r{^/}, ""))
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = config.timeout
+        http.read_timeout = config.timeout
+
+        response = http.request(Net::HTTP::Get.new(uri.request_uri))
+        unless response.is_a?(Net::HTTPSuccess)
+          raise DiscoveryError, "Discovery failed with HTTP #{response.code}"
+        end
+
+        response.body
+      rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error => e
+        raise DiscoveryError, "Discovery timed out: #{e.message}"
+      rescue SocketError, Errno::ECONNREFUSED => e
+        raise DiscoveryError, "Discovery connection failed: #{e.message}"
+      end
+
+      def parse_json(body)
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise DiscoveryError, "Discovery returned invalid JSON: #{e.message}"
+      end
+
+      def verify_issuer!(doc)
+        discovered = doc["issuer"].to_s
+        configured = config.issuer.to_s
+        return if discovered == configured
+
+        raise DiscoveryError,
+              "Discovery issuer mismatch: document said #{discovered.inspect}, " \
+              "config expected #{configured.inspect}"
+      end
+
+      def ensure_trailing_slash(url)
+        url.to_s.end_with?("/") ? url : "#{url}/"
+      end
+    end
+  end
+end

lib/activeadmin/oidc/discovery.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Oidc
+    module Presets
+      module Zitadel
+        DEFAULT_SCOPE = "openid email profile"
+
+        def self.apply(config)
+          config.scope = DEFAULT_SCOPE if config.scope == Configuration::DEFAULT_SCOPE
+          config.pkce  = true if blank?(config.client_secret) && config.instance_variable_get(:@pkce_override).nil?
+          config
+        end
+
+        def self.blank?(value)
+          value.nil? || value.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

lib/activeadmin/oidc/presets/zitadel.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Oidc
+    # Finds-or-creates an AdminUser for an OIDC callback. Runs the host's
+    # `on_login` hook (which owns all authorization decisions), then saves.
+    #
+    #   provisioner = UserProvisioner.new(config, claims: merged_claims, provider: "oidc")
+    #   admin_user  = provisioner.call  # raises ProvisioningError on denial
+    #
+    # Strategy:
+    #
+    # 1. Look up by (provider, uid). If found → update.
+    # 2. Otherwise look up by the configured identity_attribute. If that row
+    #    is already locked to a different (provider, uid) → refuse
+    #    (account-takeover guard). Otherwise adopt it.
+    # 3. Otherwise build a new record.
+    # 4. Assign the identity attribute and oidc_raw_info.
+    # 5. Call config.on_login(admin_user, claims). Falsy → deny. Truthy →
+    #    save and return.
+    #
+    # The claims hash is passed through untouched except that `access_token`
+    # and `refresh_token` (if present) are never persisted.
+    class UserProvisioner
+      # Claim keys that must never land in oidc_raw_info.
+      BLOCKED_RAW_INFO_KEYS = %w[access_token refresh_token id_token].freeze
+
+      def initialize(config, claims:, provider:)
+        @config   = config
+        @claims   = claims.transform_keys(&:to_s)
+        @provider = provider
+      end
+
+      def call
+        validate_claims!
+
+        admin_user = find_or_adopt_or_build
+        assign_base_attributes(admin_user)
+
+        allowed = @config.on_login.call(admin_user, @claims)
+        raise ProvisioningError, denial_message unless allowed
+
+        save!(admin_user)
+        admin_user
+      end
+
+      private
+
+      def model
+        @model ||= admin_user_class
+      end
+
+      def admin_user_class
+        klass_name = @config.respond_to?(:admin_user_class) && @config.admin_user_class
+        return klass_name if klass_name.is_a?(Class)
+
+        Object.const_get(klass_name || "AdminUser")
+      end
+
+      def validate_claims!
+        if blank?(@claims["sub"])
+          raise ProvisioningError, "OIDC id_token is missing a sub claim"
+        end
+
+        claim_key = @config.identity_claim.to_s
+        if blank?(@claims[claim_key])
+          raise ProvisioningError,
+                "OIDC id_token is missing identity claim #{claim_key.inspect}"
+        end
+      end
+
+      def find_or_adopt_or_build
+        uid = @claims["sub"].to_s
+        existing = model.find_by(provider: @provider, uid: uid)
+        return existing if existing
+
+        identity_value = @claims[@config.identity_claim.to_s]
+        identity_match = model.find_by(@config.identity_attribute => identity_value)
+
+        if identity_match
+          if identity_match.provider.present? || identity_match.uid.present?
+            raise ProvisioningError,
+                  "Identity #{identity_value.inspect} is already linked to a different account (takeover guard)"
+          end
+
+          identity_match.provider = @provider
+          identity_match.uid      = uid
+          return identity_match
+        end
+
+        model.new(provider: @provider, uid: uid)
+      end
+
+      def assign_base_attributes(admin_user)
+        identity_value = @claims[@config.identity_claim.to_s]
+        admin_user.public_send("#{@config.identity_attribute}=", identity_value)
+        admin_user.oidc_raw_info = sanitized_raw_info if admin_user.respond_to?(:oidc_raw_info=)
+      end
+
+      def sanitized_raw_info
+        @claims.reject { |k, _v| BLOCKED_RAW_INFO_KEYS.include?(k) }
+      end
+
+      def save!(admin_user)
+        admin_user.save!
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+        raise ProvisioningError, e.message
+      end
+
+      def denial_message
+        @config.access_denied_message
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

lib/activeadmin/oidc/user_provisioner.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "activeadmin-oidc"
+
+Dir[File.expand_path("support/**/*.rb", __dir__)].each { |f| require f }
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.disable_monkey_patching!
+  config.warnings = true
+  config.order = :random
+  Kernel.srand config.seed
+
+  config.before(:each) { ActiveAdmin::Oidc.reset! if ActiveAdmin::Oidc.respond_to?(:reset!) }
+end