devise_scim 0.1.11

data/lib/devise_scim/scim/user.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DeviseScim
+  module Scim
+    USER_SCHEMA       = "urn:ietf:params:scim:schemas:core:2.0:User"
+    ENTERPRISE_SCHEMA = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
+
+    Name        = Struct.new(:formatted, :given_name, :family_name, :middle_name,
+                             :honorific_prefix, :honorific_suffix, keyword_init: true)
+    Email       = Struct.new(:value, :type, :primary, keyword_init: true)
+    PhoneNumber = Struct.new(:value, :type, :primary, keyword_init: true)
+    Meta        = Struct.new(:resource_type, :created, :last_modified, :version, :location,
+                             keyword_init: true)
+
+    # rubocop:disable Metrics/ClassLength
+    class User
+      SCHEMAS = [USER_SCHEMA].freeze
+
+      attr_accessor :id, :external_id, :user_name, :display_name, :nick_name,
+                    :profile_url, :title, :user_type, :preferred_language,
+                    :locale, :timezone, :active, :name, :emails, :phone_numbers,
+                    :groups, :meta
+
+      class << self
+        def from_h(hash)
+          user = new
+          assign_scalars(user, hash)
+          assign_name(user, hash)
+          user.emails        = parse_emails(hash)
+          user.phone_numbers = parse_phones(hash)
+          user
+        end
+
+        private
+
+        # rubocop:disable Metrics/AbcSize
+        def assign_scalars(user, hash)
+          user.id                 = hash["id"]
+          user.external_id        = hash["externalId"]
+          user.user_name          = hash["userName"]
+          user.display_name       = hash["displayName"]
+          user.nick_name          = hash["nickName"]
+          user.profile_url        = hash["profileUrl"]
+          user.title              = hash["title"]
+          user.user_type          = hash["userType"]
+          user.preferred_language = hash["preferredLanguage"]
+          user.locale             = hash["locale"]
+          user.timezone           = hash["timezone"]
+          user.active             = hash.key?("active") ? hash["active"] : true
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def assign_name(user, hash)
+          return unless (n = hash["name"])
+
+          user.name = Name.new(
+            formatted: n["formatted"],
+            given_name: n["givenName"],
+            family_name: n["familyName"],
+            middle_name: n["middleName"],
+            honorific_prefix: n["honorificPrefix"],
+            honorific_suffix: n["honorificSuffix"]
+          )
+        end
+
+        def parse_emails(hash)
+          Array(hash["emails"]).map do |entry|
+            Email.new(value: entry["value"], type: entry["type"], primary: entry["primary"])
+          end
+        end
+
+        def parse_phones(hash)
+          Array(hash["phoneNumbers"]).map do |entry|
+            PhoneNumber.new(value: entry["value"], type: entry["type"], primary: entry["primary"])
+          end
+        end
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def to_h
+        h = base_hash.compact
+        h["schemas"] = SCHEMAS
+        h["name"]         = serialize_name           if name
+        h["emails"]       = serialize_emails         if emails&.any?
+        h["phoneNumbers"] = serialize_phones         if phone_numbers&.any?
+        h["groups"]       = groups                   if groups&.any?
+        h["meta"]         = serialize_meta(meta, "User") if meta
+        h
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def to_json(*)
+        to_h.to_json
+      end
+
+      def primary_email
+        emails&.find(&:primary)&.value || user_name
+      end
+
+      private
+
+      def base_hash
+        {
+          "schemas" => SCHEMAS,
+          "id" => id,
+          "externalId" => external_id,
+          "userName" => user_name,
+          "displayName" => display_name,
+          "nickName" => nick_name,
+          "profileUrl" => profile_url,
+          "title" => title,
+          "userType" => user_type,
+          "preferredLanguage" => preferred_language,
+          "locale" => locale,
+          "timezone" => timezone,
+          "active" => active
+        }
+      end
+
+      def serialize_name
+        {
+          "formatted" => name.formatted,
+          "givenName" => name.given_name,
+          "familyName" => name.family_name,
+          "middleName" => name.middle_name,
+          "honorificPrefix" => name.honorific_prefix,
+          "honorificSuffix" => name.honorific_suffix
+        }.compact
+      end
+
+      def serialize_emails
+        emails.map do |email|
+          { "value" => email.value, "type" => email.type, "primary" => email.primary }.compact
+        end
+      end
+
+      def serialize_phones
+        phone_numbers.map do |phone|
+          { "value" => phone.value, "type" => phone.type, "primary" => phone.primary }.compact
+        end
+      end
+
+      def serialize_meta(met, resource_type)
+        {
+          "resourceType" => met.resource_type || resource_type,
+          "created" => iso8601_or_raw(met.created),
+          "lastModified" => iso8601_or_raw(met.last_modified),
+          "version" => met.version,
+          "location" => met.location
+        }.compact
+      end
+
+      def iso8601_or_raw(value)
+        value.respond_to?(:iso8601) ? value.iso8601 : value
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/devise_scim/scim_adapter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DeviseScim
+  class ScimAdapter
+    attr_reader :record, :scim_user, :scim_group, :tenant
+
+    def initialize(record, scim_object, tenant: nil)
+      @record     = record
+      @scim_user  = scim_object if scim_object.is_a?(Scim::User)
+      @scim_group = scim_object if scim_object.is_a?(Scim::Group)
+      @tenant     = tenant
+    end
+
+    def attributes_for_create
+      base_user_attributes
+    end
+
+    def attributes_for_update
+      base_user_attributes
+    end
+
+    def after_provision;   end
+    def after_deprovision; end
+
+    def handle_group_create;  end
+    def handle_group_update;  end
+    def handle_group_destroy; end
+
+    def to_scim
+      scim            = Scim::User.new
+      scim.id         = record.id.to_s
+      scim.user_name  = record.email
+      scim.active     = resolve_active
+      scim.emails     = [Scim::Email.new(value: record.email, type: "work", primary: true)]
+      scim.name       = build_name
+      scim.meta       = build_meta("User")
+      scim
+    end
+
+    def group_to_scim
+      raise NotImplementedError, "#{self.class}#group_to_scim must be implemented when enable_groups is true"
+    end
+
+    private
+
+    def base_user_attributes
+      attrs = { email: scim_user.user_name || scim_user.primary_email }
+      attrs[:first_name] = scim_user.name&.given_name  if column?(:first_name)
+      attrs[:last_name]  = scim_user.name&.family_name if column?(:last_name)
+      attrs
+    end
+
+    def column?(name)
+      record.class.respond_to?(:column_names) &&
+        record.class.column_names.include?(name.to_s)
+    end
+
+    def resolve_active
+      if column?(:scim_active)
+        record.scim_active
+      elsif column?(:deleted_at)
+        record.deleted_at.nil?
+      else
+        true
+      end
+    end
+
+    def build_name
+      given  = column?(:first_name) ? record.first_name : nil
+      family = column?(:last_name)  ? record.last_name  : nil
+      return nil unless given || family
+
+      Scim::Name.new(given_name: given, family_name: family)
+    end
+
+    def build_meta(resource_type)
+      Scim::Meta.new(
+        resource_type: resource_type,
+        created: record.created_at,
+        last_modified: record.updated_at
+      )
+    end
+  end
+end

data/lib/devise_scim/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DeviseScim
+  VERSION = "0.1.11"
+end

data/lib/devise_scim.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "devise_scim/version"
+require_relative "devise_scim/configuration"
+
+module DeviseScim
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class NotFound      < Error; end
+  class Conflict      < Error; end
+  class InvalidFilter < Error; end
+  class Unauthorized  < Error; end
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+if defined?(Rails)
+  require_relative "devise_scim/concerns/scim_tenant"
+  require_relative "devise_scim/models/scim_tenant"
+  require_relative "devise_scim/models/scim_tenant_user"
+  require_relative "devise_scim/scim/user"
+  require_relative "devise_scim/scim/group"
+  require_relative "devise_scim/scim/list_response"
+  require_relative "devise_scim/scim/error"
+  require_relative "devise_scim/scim/patch_operation"
+  require_relative "devise_scim/scim_adapter"
+  require_relative "devise_scim/concerns/scim_group_identifiable"
+  require_relative "devise_scim/filter/parser"
+  require_relative "devise_scim/filter/arel_visitor"
+  require_relative "devise_scim/auth/base_strategy"
+  require_relative "devise_scim/auth/token_strategy"
+  require_relative "devise_scim/auth/oauth_strategy"
+  require_relative "devise_scim/middleware/authenticator"
+  require_relative "devise_scim/routing"
+  require_relative "devise_scim/engine"
+end

data/lib/generators/devise_scim/adapter_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module DeviseScim
+  module Generators
+    class AdapterGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a pre-filled ScimAdapter in app/scim/application_scim_adapter.rb"
+
+      def copy_adapter
+        template "application_scim_adapter.rb.tt", "app/scim/application_scim_adapter.rb"
+      end
+    end
+  end
+end

data/lib/generators/devise_scim/install_generator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module DeviseScim
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :model_name, type: :string, default: "User",
+                            desc: "Devise model to add SCIM fields to (e.g. User)"
+
+      class_option :multi_tenant, type: :boolean, default: false,
+                                  desc: "Generate multi-tenant migrations"
+      class_option :oauth, type: :boolean, default: false,
+                           desc: "Configure OAuth 2.0 client-credentials auth"
+      class_option :tenant_model, type: :string, default: nil,
+                                  desc: "Existing model to use as the SCIM tenant (e.g. Org). " \
+                                        "Omit to use the built-in DeviseScim::ScimTenant."
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def preflight_check
+        return unless needs_doorkeeper?
+
+        unless doorkeeper_in_gemfile?
+          say_status :error, "Doorkeeper gem not found in Gemfile.", :red
+          say "  Add `gem 'doorkeeper', '~> 5.6'` to your Gemfile and run `bundle install`.", :red
+          raise Thor::Error, "Aborting: Doorkeeper required for #{doorkeeper_reason}."
+        end
+
+        return if doorkeeper_installed?
+
+        unless yes?("Doorkeeper not yet installed. Run `rails g doorkeeper:install` now?")
+          raise Thor::Error, "Aborting. Run `rails g doorkeeper:install` before proceeding."
+        end
+
+        generate "doorkeeper:install"
+      end
+
+      def copy_user_migration
+        migration_template(
+          "add_scim_to_users.rb.tt",
+          "db/migrate/add_scim_to_#{table_name}.rb"
+        )
+      end
+
+      def copy_tenant_migrations
+        return unless options[:multi_tenant]
+
+        if options[:tenant_model]
+          migration_template "add_scim_to_tenant.rb.tt",
+                             "db/migrate/add_scim_to_#{tenant_table_name}.rb"
+        else
+          migration_template "create_scim_tenants.rb.tt", "db/migrate/create_scim_tenants.rb"
+        end
+        migration_template "create_scim_tenant_users.rb.tt", "db/migrate/create_scim_tenant_users.rb"
+      end
+
+      def copy_initializer
+        template "devise_scim.rb.tt", "config/initializers/devise_scim.rb"
+      end
+
+      private
+
+      def needs_doorkeeper?
+        options[:oauth] || options[:multi_tenant]
+      end
+
+      def doorkeeper_reason
+        options[:multi_tenant] ? "--multi-tenant mode" : "--oauth auth"
+      end
+
+      def doorkeeper_in_gemfile?
+        gemfile = File.join(destination_root, "Gemfile")
+        File.exist?(gemfile) && File.read(gemfile).include?("doorkeeper")
+      end
+
+      def doorkeeper_installed?
+        Dir[File.join(destination_root, "db/migrate/*doorkeeper*")].any? ||
+          Dir[File.join(destination_root, "db/migrate/*create_doorkeeper_tables*")].any?
+      end
+
+      def table_name
+        model_name.underscore.pluralize
+      end
+
+      def tenant_table_name
+        options[:tenant_model] ? options[:tenant_model].underscore.pluralize : "scim_tenants"
+      end
+
+      def tenant_ref_name
+        options[:tenant_model] ? options[:tenant_model].underscore : "scim_tenant"
+      end
+
+      def tenant_fk_column
+        options[:tenant_model] ? "#{options[:tenant_model].underscore}_id" : "scim_tenant_id"
+      end
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def scim_raw_type
+        adapter = ActiveRecord::Base.connection.adapter_name.downcase
+        adapter.include?("postgresql") ? "jsonb" : "text"
+      rescue StandardError
+        "text"
+      end
+    end
+  end
+end

data/lib/generators/devise_scim/templates/add_scim_to_tenant.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class AddScimTo<%= options[:tenant_model].camelize.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    unless column_exists?(:<%= tenant_table_name %>, :token_digest)
+      add_column :<%= tenant_table_name %>, :token_digest, :string
+    end
+    unless column_exists?(:<%= tenant_table_name %>, :auth_method)
+      add_column :<%= tenant_table_name %>, :auth_method, :string, null: false, default: "token"
+    end
+    unless column_exists?(:<%= tenant_table_name %>, :doorkeeper_application_id)
+      add_column :<%= tenant_table_name %>, :doorkeeper_application_id, :bigint
+      add_foreign_key :<%= tenant_table_name %>, :oauth_applications,
+                      column: :doorkeeper_application_id, on_delete: :nullify
+    end
+  end
+end

data/lib/generators/devise_scim/templates/add_scim_to_users.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class AddScimTo<%= model_name.camelize.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+<%- unless options[:multi_tenant] -%>
+    add_column :<%= table_name %>, :scim_uid, :string
+    add_index  :<%= table_name %>, :scim_uid, unique: true
+<%- end -%>
+    add_column :<%= table_name %>, :scim_provisioned,      :boolean,  default: false, null: false
+    add_column :<%= table_name %>, :scim_active,           :boolean,  default: true,  null: false
+    add_column :<%= table_name %>, :scim_source,           :string
+    add_column :<%= table_name %>, :scim_deprovisioned_at, :datetime
+    add_column :<%= table_name %>, :scim_raw,              :<%= scim_raw_type %>
+  end
+end

data/lib/generators/devise_scim/templates/application_scim_adapter.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class ApplicationScimAdapter < DeviseScim::ScimAdapter
+  # Override to customize attributes assigned on create.
+  # Must return a Hash of AR attribute names to values.
+  #
+  # def attributes_for_create
+  #   super.merge(role: "user")
+  # end
+
+  # Override to customize attributes assigned on update.
+  #
+  # def attributes_for_update
+  #   super
+  # end
+
+  # Lifecycle hooks — called after provision/deprovision completes.
+  # def after_provision;   end
+  # def after_deprovision; end
+
+  # Implement to handle SCIM Group operations.
+  # def handle_group_create;  end
+  # def handle_group_update;  end
+  # def handle_group_destroy; end
+
+  # Required when enable_groups is true. Serialize a group AR record → Scim::Group.
+  #
+  # def group_to_scim
+  #   DeviseScim::Scim::Group.new.tap do |g|
+  #     g.id           = record.id.to_s
+  #     g.display_name = record.name
+  #   end
+  # end
+end

data/lib/generators/devise_scim/templates/create_scim_tenant_users.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateScimTenantUsers < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :scim_tenant_users do |t|
+      t.references :<%= tenant_ref_name %>, null: false,
+                   foreign_key: { to_table: :<%= tenant_table_name %> }
+      t.bigint     :user_id,        null: false
+      t.string     :scim_uid
+      t.datetime   :provisioned_at
+      t.datetime   :scim_claimed_at
+      t.boolean    :active,         null: false, default: true
+      t.<%= scim_raw_type %> :scim_raw
+      t.timestamps
+    end
+
+    add_index :scim_tenant_users, [:<%= tenant_fk_column %>, :user_id],  unique: true
+    add_index :scim_tenant_users, [:<%= tenant_fk_column %>, :scim_uid], unique: true,
+              where: "scim_uid IS NOT NULL"
+    add_foreign_key :scim_tenant_users, :<%= table_name %>, column: :user_id
+  end
+end

data/lib/generators/devise_scim/templates/create_scim_tenants.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateScimTenants < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :scim_tenants do |t|
+      t.string  :name,                      null: false
+      t.string  :auth_method,               null: false, default: "token"
+      t.string  :token_digest
+      t.bigint  :doorkeeper_application_id
+      t.boolean :active,                    null: false, default: true
+      t.timestamps
+    end
+
+    add_foreign_key :scim_tenants, :oauth_applications,
+                    column: :doorkeeper_application_id,
+                    on_delete: :nullify
+  end
+end

data/lib/generators/devise_scim/templates/devise_scim.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+DeviseScim.configure do |config|
+  # Mount path for all SCIM 2.0 endpoints.
+  config.route_prefix = "/scim/v2"
+
+  # Tenancy mode. :single = one IdP; :multi = per-tenant credentials and scoping.
+  config.tenancy = :<%= options[:multi_tenant] ? "multi" : "single" %>
+
+  # Devise model that represents provisioned users.
+  config.devise_model = "<%= model_name %>"
+
+  # Expose /Groups endpoints. Implement handle_group_* in your ScimAdapter when true.
+  config.enable_groups = false
+
+  # true = destroy record on DELETE; false = set scim_active=false only.
+  config.soft_delete = true
+
+  # Behaviour when a DELETE targets a user not originally provisioned via SCIM.
+  # false = 200 OK, no action (default); true = deprovision anyway; :error = 409 Conflict.
+  config.deprovision_manual_users = false
+
+  # Adapter class that maps SCIM attributes to your model.
+  # Run `rails g devise_scim:adapter` to generate a pre-filled starting point.
+  config.adapter = nil # replace with ApplicationScimAdapter after running the adapter generator
+
+  # ── Single-tenant auth ────────────────────────────────────────────────────────
+  # Ignored in multi-tenant mode (credentials live on each ScimTenant record).
+
+  # :token = Authorization: Bearer <token>; :oauth = Doorkeeper client credentials.
+  config.auth_method = :token
+
+  # Bearer token (plain-text). Store in an env var — never commit to source control.
+  config.token = ENV.fetch("SCIM_BEARER_TOKEN", nil)
+
+  # OAuth 2.0 client credentials. Requires the doorkeeper gem.
+  config.oauth_client_id     = ENV.fetch("SCIM_CLIENT_ID", nil)
+  config.oauth_client_secret = ENV.fetch("SCIM_CLIENT_SECRET", nil)
+
+  # ── Multi-tenant options ──────────────────────────────────────────────────────
+  # Ignored in single-tenant mode.
+<% if options[:tenant_model] %>
+  # AR model used as the SCIM tenant. Defaults to DeviseScim::ScimTenant.
+  config.tenant_model = "<%= options[:tenant_model] %>"
+<% end %>
+  # :multiple = a user may belong to many tenants (default).
+  # :one_to_one = a user may belong to at most one tenant.
+  config.user_exclusivity = :multiple
+
+  # Behaviour when :one_to_one and a POST /Users matches a user in another tenant.
+  # :error = 409 Conflict (default); :reassign = move user to new tenant.
+  config.exclusivity_conflict = :error
+end

data/sig/devise_scim.rbs

@@ -0,0 +1,4 @@
+module DeviseScim
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end