activeadmin-oidc 1.0.0

data/lib/activeadmin/oidc/user_provisioner.rb

@@ -0,0 +1,142 @@
+# 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 = invoke_on_login(admin_user)
+        raise ProvisioningError, denial_message unless allowed
+
+        save!(admin_user)
+        admin_user
+      rescue RetryProvisioning
+        # Concurrent JIT provisioning: another thread inserted first.
+        # Re-run once — find_or_adopt_or_build will now find the record.
+        retry
+      end
+
+      private
+
+      def model
+        @model ||= resolve_admin_user_class
+      end
+
+      def resolve_admin_user_class
+        @config.admin_user_class.is_a?(Class) ? @config.admin_user_class : @config.admin_user_class.constantize
+      end
+
+      def validate_claims!
+        if @claims["sub"].blank?
+          raise ProvisioningError, "OIDC id_token is missing a sub claim"
+        end
+
+        claim_key = @config.identity_claim.to_s
+        if @claims[claim_key].blank?
+          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::RecordNotUnique
+        raise ProvisioningError, denial_message if @retried
+
+        # Concurrent JIT provisioning race: the other thread won the
+        # insert. Re-run call once to find the now-persisted record.
+        @retried = true
+        raise RetryProvisioning
+      rescue ActiveRecord::RecordInvalid => e
+        raise ProvisioningError, e.message
+      end
+
+      # The on_login hook is host-app code. If it raises a non-gem
+      # exception, we do NOT want the callback action to blow up with
+      # a 500 — the cleanest UX is the same generic denial flash the
+      # "hook returned false" path produces. We still log the original
+      # exception class + message at error level so ops can debug.
+      # Gem-internal exceptions (ActiveAdmin::Oidc::Error subclasses)
+      # are re-raised untouched so nested provisioning errors surface
+      # with their original messages.
+      def invoke_on_login(admin_user)
+        @config.on_login.call(admin_user, @claims)
+      rescue ActiveAdmin::Oidc::Error
+        raise
+      rescue StandardError => e
+        ActiveAdmin::Oidc.logger.error(
+          "[activeadmin-oidc] on_login hook raised #{e.class}: #{e.message}"
+        )
+        raise ProvisioningError, denial_message
+      end
+
+      def denial_message
+        @config.access_denied_message
+      end
+    end
+  end
+end

data/lib/activeadmin/oidc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module Oidc
+    VERSION = "1.0.0"
+  end
+end

data/lib/activeadmin-oidc.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "logger"
+require "active_support/core_ext/object/blank"
+require "activeadmin/oidc/version"
+
+# `omniauth-rails_csrf_protection` registers a Railtie that replaces
+# OmniAuth 2.x's Rack-level authenticity check with Rails' own forgery
+# protection. It's a runtime dependency of this gem, but `Bundler.require`
+# in host apps only auto-requires top-level Gemfile entries — not
+# transitive deps pulled in via our gemspec. We `require` it here so
+# that the railtie gets loaded whenever a host does
+# `gem "activeadmin-oidc"`, and CSRF-protected OmniAuth POSTs work
+# out of the box with `button_to`-style login buttons.
+#
+# `omniauth/rails_csrf_protection/railtie` references `Rails::Railtie`
+# at file load, so pull in the minimal Railtie base class first — this
+# keeps the require safe even in spec_helper contexts where the full
+# Rails stack hasn't been initialized yet.
+require "rails/railtie"
+require "omniauth/rails_csrf_protection"
+
+module ActiveAdmin
+  module Oidc
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class ProvisioningError < Error; end
+    class RetryProvisioning < Error; end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        config
+      end
+
+      # Logger the gem uses for internal diagnostics (on_login hook
+      # failures, omniauth failures, etc). Defaults to Rails.logger when
+      # Rails is booted, falls back to a null logger otherwise so that
+      # library code is safe to call in non-Rails contexts (unit specs,
+      # scripts). Override by assigning directly — useful in tests.
+      def logger
+        @logger || default_logger
+      end
+
+      attr_writer :logger
+
+      def reset!
+        @config = Configuration.new
+        @logger = nil
+      end
+
+      private
+
+      def default_logger
+        if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+          ::Rails.logger
+        else
+          @null_logger ||= ::Logger.new(IO::NULL)
+        end
+      end
+    end
+  end
+end
+
+require "activeadmin/oidc/configuration"
+require "activeadmin/oidc/user_provisioner"
+require "rails/engine"
+require "activeadmin/oidc/engine"

data/lib/generators/active_admin/oidc/install/install_generator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ActiveAdmin
+  module Oidc
+    module Generators
+      # `bin/rails generate active_admin:oidc:install`
+      #
+      # Produces a working starting point for the host app:
+      #
+      #   * config/initializers/activeadmin_oidc.rb  (commented template)
+      #   * db/migrate/<ts>_add_oidc_to_admin_users.rb
+      #   * app/views/active_admin/devise/sessions/new.html.erb (override)
+      #
+      # Idempotent: running twice is a no-op for all three files (the
+      # migration is skipped if an *_add_oidc_to_admin_users.rb file
+      # already exists on disk, even with a different timestamp).
+      #
+      # Refuses to run if the host app is missing an `AdminUser` model
+      # or the `devise` / `activeadmin` gems — those are the sharp
+      # corners it can't work around, and silently succeeding would
+      # produce broken configuration.
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Installs activeadmin-oidc into the host Rails app."
+
+        def self.next_migration_number(dirname)
+          ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+        end
+
+        def verify_host_app!
+          unless File.exist?(File.join(destination_root, "app/models/admin_user.rb"))
+            raise ::Thor::Error,
+                  "activeadmin-oidc: could not find app/models/admin_user.rb — " \
+                  "install activeadmin + devise first and make sure the AdminUser " \
+                  "model exists."
+          end
+
+          gemfile_lock = File.join(destination_root, "Gemfile.lock")
+          lock_contents = File.exist?(gemfile_lock) ? File.read(gemfile_lock) : ""
+
+          unless lock_contents.match?(/^\s+devise\b/)
+            raise ::Thor::Error,
+                  "activeadmin-oidc: devise not found in Gemfile.lock. " \
+                  "Add `gem \"devise\"` and run `bundle install` first."
+          end
+
+          unless lock_contents.match?(/^\s+activeadmin\b/)
+            raise ::Thor::Error,
+                  "activeadmin-oidc: activeadmin not found in Gemfile.lock. " \
+                  "Add `gem \"activeadmin\"` and run `bundle install` first."
+          end
+        end
+
+        def create_initializer
+          template "initializer.rb.tt", "config/initializers/activeadmin_oidc.rb"
+        end
+
+        def create_migration_file
+          # Idempotency: if a previous run already produced this
+          # migration (any timestamp), do nothing. We never want to
+          # stack up duplicate add_column migrations.
+          existing = Dir[File.join(destination_root, "db/migrate/*_add_oidc_to_admin_users.rb")]
+          return if existing.any?
+
+          @raw_info_type = raw_info_column_type
+          migration_template "migration.rb.tt",
+                             "db/migrate/add_oidc_to_admin_users.rb"
+        end
+
+        def create_view_override
+          copy_file "sessions_new.html.erb",
+                    "app/views/active_admin/devise/sessions/new.html.erb"
+        end
+
+        # Non-blocking: the generator completed successfully, but the
+        # host AdminUser may be missing the Devise modules the gem needs.
+        # We warn rather than hard-fail because a mid-refactor user may
+        # know exactly what they're doing.
+        def warn_missing_admin_user_wiring
+          admin_user_path = File.join(destination_root, "app/models/admin_user.rb")
+          return unless File.exist?(admin_user_path)
+
+          contents = File.read(admin_user_path)
+
+          unless contents.match?(/:omniauthable/)
+            say_status :warning,
+                       "app/models/admin_user.rb does not include :omniauthable — " \
+                       "add `:omniauthable, omniauth_providers: [:oidc]` to your `devise` call.",
+                       :yellow
+          end
+
+          unless contents.match?(/omniauth_providers\s*:\s*\[\s*:oidc/)
+            say_status :warning,
+                       "app/models/admin_user.rb does not declare `omniauth_providers: [:oidc]` — " \
+                       "the gem's callback controller will not be reachable without it.",
+                       :yellow
+          end
+        end
+
+        # Print a short checklist of the host-app wiring the generator
+        # can't do itself. These are the footguns that cost us an hour
+        # the first time we wired a fresh demo app: commented-out
+        # `authentication_method` / `current_user_method` in the
+        # ActiveAdmin initializer, and forgetting to migrate.
+        def print_next_steps
+          say ""
+          say "=" * 60, :green
+          say "activeadmin-oidc: next steps", :green
+          say "=" * 60, :green
+          say <<~STEPS
+            1. In config/initializers/active_admin.rb, uncomment:
+                 config.authentication_method = :authenticate_admin_user!
+                 config.current_user_method   = :current_admin_user
+               Without these, /admin is public and the utility nav
+               (including the logout button) renders empty.
+
+            2. In app/models/admin_user.rb, make sure the devise call
+               includes:
+                 :omniauthable, omniauth_providers: [:oidc]
+
+            3. Fill in the generated config/initializers/activeadmin_oidc.rb
+               with your issuer and client_id (plus client_secret if you
+               are NOT using PKCE public-client mode).
+
+            4. Apply the generated migration:
+                 bin/rails db:migrate
+          STEPS
+          say "=" * 60, :green
+        end
+
+        private
+
+        # Postgres gets `jsonb` (fast, indexable), everything else
+        # falls back to `:text` so sqlite/mysql hosts aren't left out.
+        def raw_info_column_type
+          adapter = (ActiveRecord::Base.connection_db_config.adapter rescue "sqlite3").to_s
+          adapter.start_with?("postgres") ? ":jsonb" : ":text"
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_admin/oidc/install/templates/initializer.rb.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# activeadmin-oidc initializer — generated by
+#   bin/rails generate active_admin:oidc:install
+#
+# Uncomment and fill in the values for your identity provider.
+
+ActiveAdmin::Oidc.configure do |c|
+  # --- Provider ---------------------------------------------------------
+  # 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
+
+  # --- Identity lookup --------------------------------------------------
+  # Which AdminUser column to match against when a (provider, uid) lookup
+  # misses and we need to migrate an existing row to SSO, and which claim
+  # on the id_token/userinfo to read it from.
+  # c.identity_attribute = :email
+  # c.identity_claim     = :email
+
+  # --- Login button label ----------------------------------------------
+  # c.login_button_label = "Sign in with Corporate SSO"
+
+  # --- on_login hook ---------------------------------------------------
+  # Called with (admin_user, claims) after identity lookup and before
+  # save. Mutate admin_user in place, return truthy to allow sign-in,
+  # return falsy to deny. This is the ONLY place authorization lives —
+  # the gem does not ship a role model.
+  #
+  # Example A — Zitadel with nested project roles claim:
+  #
+  #   c.on_login = ->(admin_user, claims) {
+  #     roles = claims["urn:zitadel:iam:org:project:roles"]&.keys || []
+  #     return false if roles.empty?
+  #     admin_user.roles = roles
+  #     true
+  #   }
+  #
+  # Example B — department-style authorization:
+  #
+  #   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
+  #   }
+end

data/lib/generators/active_admin/oidc/install/templates/migration.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddOidcToAdminUsers < ActiveRecord::Migration[7.0]
+  def change
+    add_column :admin_users, :provider,      :string
+    add_column :admin_users, :uid,           :string
+    add_column :admin_users, :oidc_raw_info, <%= @raw_info_type %>
+
+    add_index  :admin_users, [:provider, :uid], unique: true
+  end
+end

data/lib/generators/active_admin/oidc/install/templates/sessions_new.html.erb

@@ -0,0 +1,9 @@
+<div id="login">
+  <h2><%%= active_admin_application.site_title(self) %></h2>
+
+  <%%= button_to ActiveAdmin::Oidc.config.login_button_label,
+                "/admin/auth/oidc",
+                method: :post,
+                class: "activeadmin-oidc-login-button",
+                data: { turbo: false } %>
+</div>