powerhome-scimitar 1.0.0

data/config/initializers/scimitar.rb

@@ -0,0 +1,111 @@
+# SCIMITAR CONFIGURATION
+#
+# For supporting information and rationale, please see README.md.
+
+Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
+
+  # ===========================================================================
+  # SERVICE PROVIDER CONFIGURATION
+  # ===========================================================================
+  #
+  # This is a Ruby abstraction over a SCIM entity that declares the
+  # capabilities supported by a particular implementation.
+  #
+  # Typically this is used to declare parts of the standard unsupported, if you
+  # don't need them and don't want to provide subclass support.
+  #
+  Scimitar.service_provider_configuration = Scimitar::ServiceProviderConfiguration.new({
+
+    # See https://tools.ietf.org/html/rfc7643#section-8.5 for properties.
+    #
+    # See Gem file 'app/models/scimitar/service_provider_configuration.rb'
+    # for defaults. Define Hash keys here that override defaults; e.g. to
+    # declare that filters are not supported so that calling clients shouldn't
+    # use them:
+    #
+    #   filter: Scimitar::Supported.unsupported
+
+  })
+
+  # ===========================================================================
+  # ENGINE CONFIGURATION
+  # ===========================================================================
+  #
+  # This is where you provide callbacks for things like authorisation or mixins
+  # that get included into all Scimitar-derived controllers (for things like
+  # before-actions that apply to all Scimitar controller-based routes).
+  #
+  Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
+
+    # If you have filters you want to run for any Scimitar action/route, you
+    # can define them here. You can also override any shared controller methods
+    # here. For example, you might use a before-action to set up some
+    # multi-tenancy related state, skip Rails CSRF token verification, or
+    # customise how Scimitar generates URLs:
+    #
+    #     application_controller_mixin: Module.new do
+    #       def self.included(base)
+    #         base.class_eval do
+    #
+    #           # Anything here is written just as you'd write it at the top of
+    #           # one of your controller classes, but it gets included in all
+    #           # Scimitar classes too.
+    #
+    #           skip_before_action    :verify_authenticity_token
+    #           prepend_before_action :setup_some_kind_of_multi_tenancy_data
+    #         end
+    #       end
+    #
+    #       def scim_schemas_url(options)
+    #         super(custom_param: 'value', **options)
+    #       end
+    #     end, # ...other configuration entries might follow...
+
+    # If you want to support username/password authentication:
+    #
+    #     basic_authenticator: Proc.new do | username, password |
+    #       # Check username/password and return 'true' if valid, else 'false'.
+    #     end, # ...other configuration entries might follow...
+    #
+    # The 'username' and 'password' parameters come from Rails:
+    #
+    #   https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic.html
+    #   https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods.html#method-i-authenticate_with_http_basic
+
+    # If you want to support HTTP bearer token (OAuth-style) authentication:
+    #
+    #     token_authenticator: Proc.new do | token, options |
+    #       # Check token and return 'true' if valid, else 'false'.
+    #     end, # ...other configuration entries might follow...
+    #
+    # The 'token' and 'options' parameters come from Rails:
+    #
+    #   https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Token.html
+    #   https://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Token/ControllerMethods.html#method-i-authenticate_with_http_token
+    #
+    # Note that both basic and token authentication can be declared, with the
+    # parameters in the inbound HTTP request determining which is invoked.
+
+    # Scimitar rescues certain error cases and exceptions, in order to return a
+    # JSON response to the API caller. If you want exceptions to also be
+    # reported to a third party system such as sentry.io or raygun.com, you can
+    # configure a Proc to do so. It is passed a Ruby exception subclass object.
+    # For example, a minimal sentry.io reporter might do this:
+    #
+    #     exception_reporter: Proc.new do | exception |
+    #       Sentry.capture_exception(exception)
+    #     end
+    #
+    # You will still need to configure your reporting system according to its
+    # documentation (e.g. via a Rails "config/initializers/<foo>.rb" file).
+
+    # Scimilar treats "VDTP" (Value, Display, Type, Primary) attribute values,
+    # used for e.g. e-mail addresses or phone numbers, as required by default.
+    # If you encounter a service which calls these with e.g. "null" value data,
+    # you can configure all values to be optional. You'll need to deal with
+    # whatever that means for you receiving system in your model code.
+    #
+    #     optional_value_fields_required: false
+  })
+
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+Scimitar::Engine.routes.draw do
+  get 'ServiceProviderConfig', to: 'service_provider_configurations#show', as: :scim_service_provider_configuration
+  get 'ResourceTypes',         to: 'resource_types#index',                 as: :scim_resource_types
+  get 'ResourceTypes/:name',   to: 'resource_types#show',                  as: :scim_resource_type
+  get 'Schemas',               to: 'schemas#index',                        as: :scim_schemas
+end

data/lib/scimitar/engine.rb

@@ -0,0 +1,63 @@
+module Scimitar
+  class Engine < ::Rails::Engine
+    isolate_namespace Scimitar
+
+    Mime::Type.register 'application/scim+json', :scim
+
+    ActionDispatch::Request.parameter_parsers[Mime::Type.lookup('application/scim+json').symbol] = lambda do |body|
+      JSON.parse(body)
+    end
+
+    def self.resources
+      default_resources + custom_resources
+    end
+
+    # Can be used to add a new resource type which is not provided by the gem.
+    # For example:
+    #
+    #     module Scim
+    #       module Resources
+    #         class ShinyResource < Scimitar::Resources::Base
+    #           set_schema Scim::Schema::Shiny
+    #
+    #           def self.endpoint
+    #             "/Shinies"
+    #           end
+    #         end
+    #       end
+    #     end
+    #
+    #     Scimitar::Engine.add_custom_resource Scim::Resources::ShinyResource
+    #
+    def self.add_custom_resource(resource)
+      custom_resources << resource
+    end
+
+    # Resets the resource list to default. This is really only intended for use
+    # during testing, to avoid one test polluting another.
+    #
+    def self.reset_custom_resources
+      @custom_resources = []
+    end
+
+    # Returns the list of custom resources, if any.
+    #
+    def self.custom_resources
+      @custom_resources ||= []
+    end
+
+    # Returns the default resources added in this gem:
+    #
+    # * Scimitar::Resources::User
+    # * Scimitar::Resources::Group
+    #
+    def self.default_resources
+      [ Resources::User, Resources::Group ]
+    end
+
+    def self.schemas
+      resources.map(&:schemas).flatten.uniq.map(&:new)
+    end
+
+  end
+end

data/lib/scimitar/support/hash_with_indifferent_case_insensitive_access.rb

@@ -0,0 +1,216 @@
+require 'active_support/hash_with_indifferent_access'
+
+class Hash
+
+  # Converts this Hash to an instance of
+  # Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess, which is
+  # a subclass of ActiveSupport::HashWithIndifferentAccess with the addition of
+  # case-insensitive lookup.
+  #
+  # Note that this is more thorough than the ActiveSupport counterpart. It
+  # converts recursively, so that all Hashes to arbitrary depth, including any
+  # hashes inside Arrays, are converted. This is an expensive operation.
+  #
+  def with_indifferent_case_insensitive_access
+    self.class.deep_indifferent_case_insensitive_access(self)
+  end
+
+  # Supports #with_indifferent_case_insensitive_access. Converts the given item
+  # to indifferent, case-insensitive access as a Hash; or converts Array items
+  # if given an Array; or returns the given object.
+  #
+  # Hashes and Arrays at all depths are duplicated as a result.
+  #
+  def self.deep_indifferent_case_insensitive_access(object)
+    if object.is_a?(Hash)
+      new_hash = Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess.new
+      object.each do | key, value |
+        new_hash[key] = deep_indifferent_case_insensitive_access(value)
+      end
+      new_hash
+
+    elsif object.is_a?(Array)
+      object.map do | array_entry |
+        deep_indifferent_case_insensitive_access(array_entry)
+      end
+
+    else
+      object
+
+    end
+  end
+end
+
+module Scimitar
+  module Support
+
+    # A subclass of ActiveSupport::HashWithIndifferentAccess where not only
+    # can Hash keys be queried as Symbols or Strings, but they are looked up
+    # in a case-insensitive fashion too.
+    #
+    # During enumeration, Hash keys will always be returned in whatever case
+    # they were originally set. Just as with
+    # ActiveSupport::HashWithIndifferentAccess, though, the type of the keys is
+    # always returned as a String, even if originally set as a Symbol - only
+    # the upper/lower case nature of the original key is preserved.
+    #
+    # If a key is written more than once with the same effective meaning in a
+    # to-string, to-downcase form, then whatever case was used *first* wins;
+    # e.g. if you did hash['User'] = 23, then hash['USER'] = 42, the result
+    # would be {"User" => 42}.
+    #
+    # It's important to remember that Hash#merge is shallow and replaces values
+    # found at existing keys in the target ("this") hash with values in the
+    # inbound Hash. If that new value that is itself a Hash, this *replaces*
+    # the value. For example:
+    #
+    # * Original: <tt>'Foo' => { 'Bar' => 42 }</tt>
+    # * Merge:    <tt>'FOO' => { 'BAR' => 24 }</tt>
+    #
+    # ...results in "this" target hash's key +Foo+ being addressed in the merge
+    # by inbound key +FOO+, so the case doesn't change. But the value for +Foo+
+    # is _replaced_ by the merging-in Hash completely:
+    #
+    # * Result: <tt>'Foo' => { 'BAR' => 24 }</tt>
+    #
+    # ...and of course we might've replaced with a totally different type, such
+    # as +true+:
+    #
+    # * Original: <tt>'Foo' => { 'Bar' => 42 }</tt>
+    # * Merge:    <tt>'FOO' => true</tt>
+    # * Result:   <tt>'Foo' => true</tt>
+    #
+    # If you're intending to merge nested Hashes, then use ActiveSupport's
+    # #deep_merge or an equivalent. This will have the expected outcome, where
+    # the hash with 'BAR' is _merged_ into the existing value and, therefore,
+    # the original 'Bar' key case is preserved:
+    #
+    # * Original:   <tt>'Foo' => { 'Bar' => 42 }</tt>
+    # * Deep merge: <tt>'FOO' => { 'BAR' => 24 }</tt>
+    # * Result:     <tt>'Foo' => { 'Bar' => 24 }</tt>
+    #
+    class HashWithIndifferentCaseInsensitiveAccess < ActiveSupport::HashWithIndifferentAccess
+      def with_indifferent_case_insensitive_access
+        self
+      end
+
+      def initialize(constructor = nil)
+        @scimitar_hash_with_indifferent_case_insensitive_access_key_map = {}
+        super
+      end
+
+      # It's vital that the attribute map is carried over when one of these
+      # objects is duplicated. Duplication of this ivar state does *not* happen
+      # when 'dup' is called on our superclass, so we have to do that manually.
+      #
+      def dup
+        duplicate = super
+        duplicate.instance_variable_set(
+          '@scimitar_hash_with_indifferent_case_insensitive_access_key_map',
+          @scimitar_hash_with_indifferent_case_insensitive_access_key_map
+        )
+
+        return duplicate
+      end
+
+      # Override the individual key writer.
+      #
+      def []=(key, value)
+        string_key      = scimitar_hash_with_indifferent_case_insensitive_access_string(key)
+        indifferent_key = scimitar_hash_with_indifferent_case_insensitive_access_downcase(string_key)
+        converted_value = convert_value(value, conversion: :assignment)
+
+        # Note '||=', as there might have been a prior use of the "same" key in
+        # a different case. The earliest one is preserved since the actual Hash
+        # underneath all this is already using that variant of the key.
+        #
+        key_for_writing = (
+          @scimitar_hash_with_indifferent_case_insensitive_access_key_map[indifferent_key] ||= string_key
+        )
+
+        regular_writer(key_for_writing, converted_value)
+      end
+
+      # Override #merge to express it in terms of #merge! (also overridden), so
+      # that merged hashes can have their keys treated indifferently too.
+      #
+      def merge(*other_hashes, &block)
+        dup.merge!(*other_hashes, &block)
+      end
+
+      # Modifies-self version of #merge, overriding Hash#merge!.
+      #
+      def merge!(*hashes_to_merge_to_self, &block)
+        if block_given?
+          hashes_to_merge_to_self.each do |hash_to_merge_to_self|
+            hash_to_merge_to_self.each_pair do |key, value|
+              value = block.call(key, self[key], value) if self.key?(key)
+              self[key] = value
+            end
+          end
+        else
+          hashes_to_merge_to_self.each do |hash_to_merge_to_self|
+            hash_to_merge_to_self.each_pair do |key, value|
+              self[key] = value
+            end
+          end
+        end
+
+        self
+      end
+
+      # =======================================================================
+      # PRIVATE INSTANCE METHODS
+      # =======================================================================
+      #
+      private
+
+        if Symbol.method_defined?(:name)
+          def scimitar_hash_with_indifferent_case_insensitive_access_string(key)
+            key.kind_of?(Symbol) ? key.name : key
+          end
+        else
+          def scimitar_hash_with_indifferent_case_insensitive_access_string(key)
+            key.kind_of?(Symbol) ? key.to_s : key
+          end
+        end
+
+        def scimitar_hash_with_indifferent_case_insensitive_access_downcase(key)
+          key.kind_of?(String) ? key.downcase : key
+        end
+
+        def convert_key(key)
+          string_key      = scimitar_hash_with_indifferent_case_insensitive_access_string(key)
+          indifferent_key = scimitar_hash_with_indifferent_case_insensitive_access_downcase(string_key)
+
+          @scimitar_hash_with_indifferent_case_insensitive_access_key_map[indifferent_key] || string_key
+        end
+
+        def convert_value(value, conversion: nil)
+          if value.is_a?(Hash)
+            if conversion == :to_hash
+              value.to_hash
+            else
+              value.with_indifferent_case_insensitive_access
+            end
+          else
+            super
+          end
+        end
+
+        def update_with_single_argument(other_hash, block)
+          if other_hash.is_a?(HashWithIndifferentCaseInsensitiveAccess)
+            regular_update(other_hash, &block)
+          else
+            other_hash.to_hash.each_pair do |key, value|
+              if block && key?(key)
+                value = block.call(self.convert_key(key), self[key], value)
+              end
+              self.[]=(key, value)
+            end
+          end
+        end
+
+    end
+  end
+end

data/lib/scimitar/support/utilities.rb

@@ -0,0 +1,51 @@
+module Scimitar
+
+  # Namespace containing various chunks of Scimitar support code that don't
+  # logically fit into other areas.
+  #
+  module Support
+
+    # A namespace that contains various stand-alone utility methods which act
+    # as helpers for other parts of the code base, without risking namespace
+    # pollution by e.g. being part of a module loaded into a client class.
+    #
+    module Utilities
+
+      # Takes an array of components that usually come from a dotted path such
+      # as <tt>foo.bar.baz</tt>, along with a value that is found at the end of
+      # that path, then converts it into a nested Hash with each level of the
+      # Hash corresponding to a step along the path.
+      #
+      # This was written to help with edge case SCIM uses where (most often, at
+      # least) inbound calls use a dotted notation where nested values are more
+      # commonly accepted; converting to nesting makes it easier for subsequent
+      # processing code, which needs only handle nested Hash data.
+      #
+      # As an example, passing:
+      #
+      #     ['foo', 'bar', 'baz'], 'value'
+      #
+      # ...yields:
+      #
+      #     {'foo' => {'bar' => {'baz' => 'value'}}}
+      #
+      # Parameters:
+      #
+      # +array+:: Array containing path components, usually acquired from a
+      #           string with dot separators and a call to String#split.
+      #
+      # +value+:: The value found at the path indicated by +array+.
+      #
+      # If +array+ is empty, +value+ is returned directly, with no nesting
+      # Hash wrapping it.
+      #
+      def self.dot_path(array, value)
+        return value if array.empty?
+
+        {}.tap do | hash |
+          hash[array.shift()] = self.dot_path(array, value)
+        end
+      end
+    end
+  end
+end

data/lib/scimitar/version.rb

@@ -0,0 +1,13 @@
+module Scimitar
+
+  # Gem version. If this changes, be sure to re-run "bundle install" or
+  # "bundle update".
+  #
+  VERSION = '1.0.0'
+
+  # Date for VERSION. If this changes, be sure to re-run "bundle install"
+  # or "bundle update".
+  #
+  DATE = '2024-04-23'
+
+end

data/lib/scimitar.rb

@@ -0,0 +1,29 @@
+require 'scimitar/version'
+require 'scimitar/support/hash_with_indifferent_case_insensitive_access'
+require 'scimitar/support/utilities'
+require 'scimitar/engine'
+
+module Scimitar
+  def self.service_provider_configuration=(custom_configuration)
+    if @service_provider_configuration.nil? || ! custom_configuration.uses_defaults
+      @service_provider_configuration = custom_configuration
+    end
+  end
+
+  def self.service_provider_configuration(location:)
+    @service_provider_configuration ||= ServiceProviderConfiguration.new
+    @service_provider_configuration.meta.location = location
+    @service_provider_configuration
+  end
+
+  def self.engine_configuration=(custom_configuration)
+    if @engine_configuration.nil? || ! custom_configuration.uses_defaults
+      @engine_configuration = custom_configuration
+    end
+  end
+
+  def self.engine_configuration
+    @engine_configuration ||= EngineConfiguration.new
+    @engine_configuration
+  end
+end

data/spec/apps/dummy/app/controllers/custom_create_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'create' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomCreateMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def create
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_destroy_mock_users_controller.rb

@@ -0,0 +1,24 @@
+# For tests only - uses custom 'destroy' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#destroy.
+#
+class CustomDestroyMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  NOT_REALLY_DELETED_USERNAME_INDICATOR = 'not really deleted'
+
+  def destroy
+    super do | resource |
+      resource.update!(username: NOT_REALLY_DELETED_USERNAME_INDICATOR)
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_replace_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'replace' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomReplaceMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def replace
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_request_verifiers_controller.rb

@@ -0,0 +1,30 @@
+# For tests only - uses custom 'index' implementation which returns information
+# from the Rails 'request' object in its response.
+#
+class CustomRequestVerifiersController < Scimitar::ActiveRecordBackedResourcesController
+
+  def index
+    render json: {
+      request: {
+        is_scim: request.format == :scim,
+        format: request.format.to_s,
+        content_type: request.headers['CONTENT_TYPE']
+      }
+    }
+  end
+
+  def create
+    # Used for invalid JSON input tests
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_save_mock_users_controller.rb

@@ -0,0 +1,24 @@
+# For tests only - uses custom 'save!' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#save!.
+#
+class CustomSaveMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  CUSTOM_SAVE_BLOCK_USERNAME_INDICATOR = 'Custom save-block invoked'
+
+  protected
+
+    def save!(_record)
+      super do | record |
+        record.update!(username: CUSTOM_SAVE_BLOCK_USERNAME_INDICATOR)
+      end
+    end
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'update' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomUpdateMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def update
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/mock_groups_controller.rb

@@ -0,0 +1,13 @@
+class MockGroupsController < Scimitar::ActiveRecordBackedResourcesController
+
+  protected
+
+    def storage_class
+      MockGroup
+    end
+
+    def storage_scope
+      MockGroup.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/mock_users_controller.rb

@@ -0,0 +1,13 @@
+class MockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end