scimitar 1.8.1 → 1.10.0

data/app/models/scimitar/schema/name.rb

@@ -6,8 +6,8 @@ module Scimitar
 
       def self.scim_attributes
         @scim_attributes ||= [
-          Attribute.new(name: 'familyName',       type: 'string', required: true),
-          Attribute.new(name: 'givenName',        type: 'string', required: true),
+          Attribute.new(name: 'familyName',       type: 'string'),
+          Attribute.new(name: 'givenName',        type: 'string'),
           Attribute.new(name: 'middleName',       type: 'string'),
           Attribute.new(name: 'formatted',        type: 'string'),
           Attribute.new(name: 'honorificPrefix',  type: 'string'),

data/app/models/scimitar/schema/user.rb

@@ -20,7 +20,7 @@ module Scimitar
         [
           Attribute.new(name: 'userName',          type: 'string', uniqueness: 'server', required: true),
 
-          Attribute.new(name: 'name', complexType: Scimitar::ComplexTypes::Name),
+          Attribute.new(name: 'name',              complexType: Scimitar::ComplexTypes::Name),
 
           Attribute.new(name: 'displayName',       type: 'string'),
           Attribute.new(name: 'nickName',          type: 'string'),
@@ -35,15 +35,15 @@ module Scimitar
 
           Attribute.new(name: 'password',          type: 'string', mutability: 'writeOnly', returned: 'never'),
 
-          Attribute.new(name: 'emails',           multiValued: true, complexType: Scimitar::ComplexTypes::Email),
-          Attribute.new(name: 'phoneNumbers',     multiValued: true, complexType: Scimitar::ComplexTypes::PhoneNumber),
-          Attribute.new(name: 'ims',              multiValued: true, complexType: Scimitar::ComplexTypes::Ims),
-          Attribute.new(name: 'photos',           multiValued: true, complexType: Scimitar::ComplexTypes::Photo),
-          Attribute.new(name: 'addresses',        multiValued: true, complexType: Scimitar::ComplexTypes::Address),
-          Attribute.new(name: 'groups',           multiValued: true, complexType: Scimitar::ComplexTypes::ReferenceGroup, mutability: 'readOnly'),
-          Attribute.new(name: 'entitlements',     multiValued: true, complexType: Scimitar::ComplexTypes::Entitlement),
-          Attribute.new(name: 'roles',            multiValued: true, complexType: Scimitar::ComplexTypes::Role),
-          Attribute.new(name: 'x509Certificates', multiValued: true, complexType: Scimitar::ComplexTypes::X509Certificate),
+          Attribute.new(name: 'emails',            multiValued: true, complexType: Scimitar::ComplexTypes::Email),
+          Attribute.new(name: 'phoneNumbers',      multiValued: true, complexType: Scimitar::ComplexTypes::PhoneNumber),
+          Attribute.new(name: 'ims',               multiValued: true, complexType: Scimitar::ComplexTypes::Ims),
+          Attribute.new(name: 'photos',            multiValued: true, complexType: Scimitar::ComplexTypes::Photo),
+          Attribute.new(name: 'addresses',         multiValued: true, complexType: Scimitar::ComplexTypes::Address),
+          Attribute.new(name: 'groups',            multiValued: true, complexType: Scimitar::ComplexTypes::ReferenceGroup, mutability: 'readOnly'),
+          Attribute.new(name: 'entitlements',      multiValued: true, complexType: Scimitar::ComplexTypes::Entitlement),
+          Attribute.new(name: 'roles',             multiValued: true, complexType: Scimitar::ComplexTypes::Role),
+          Attribute.new(name: 'x509Certificates',  multiValued: true, complexType: Scimitar::ComplexTypes::X509Certificate),
         ]
       end
 

data/config/initializers/scimitar.rb

@@ -106,6 +106,47 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
     # whatever that means for you receiving system in your model code.
     #
     #     optional_value_fields_required: false
+
+    # The SCIM standard `/Schemas` endpoint lists, by default, all known schema
+    # definitions with the mutabilty (read-write, read-only, write-only) state
+    # described by those definitions, and includes all defined attributes. For
+    # user-defined schema, this will typically exactly match your underlying
+    # mapped attribute and model capability - it wouldn't make sense to define
+    # your own schema that misrepresented the implementation! For core SCIM RFC
+    # schema, though, you might want to only list actually mapped attributes.
+    # Further, if you happen to have a non-compliant implementation especially
+    # in relation to mutability of some attributes, you may want to report that
+    # accurately in the '/Schemas' list, for auto-discovery purposes. To switch
+    # to a significantly slower but more accurate render method for the list,
+    # driven by your resource subclasses and their attribute maps, set:
+    #
+    #     schema_list_from_attribute_mappings: [...array...]
+    #
+    # ...where you provide an Array of *models*, your classes that include the
+    # Scimitar::Resources::Mixin module and, therefore, define an attribute map
+    # translating SCIM schema attributes into actual implemented data. These
+    # must *uniquely* describe, via the Scimitar resources they each declare in
+    # their Scimitar::Resources::Mixin::scim_resource_type implementation, the
+    # set of schemas and extended schemas you want to render. Should resources
+    # share schema, the '/Schemas' endpoint will fail since it cannot determine
+    # which model attribute map it should use and it needs the map in order to
+    # resolve the differences (if any) between what the schema might say, and
+    # what the actual underlying model supports.
+    #
+    # It is further _very_ _strongly_ _recommended_ that, for any
+    # +scim_attributes_map+ containing a collection which has "list:" key (for
+    # an associative array of zero or more entities; the Groups to which a User
+    # might belong is a good example) then you should also specify the "class:"
+    # key, giving the class used for objects in that associated collection. The
+    # class *must* include Scimitar::Resources::Mixin, since its own attribute
+    # map is consulted in order to render the part of the schema describing
+    # those associated properties in the owning resource. If you don't do this,
+    # and if you're using ActiveRecord, then Scimitar attempts association
+    # reflection to determine the collection class - but that's more fragile
+    # than just being told the exact class in the attribute map. No matter how
+    # this class is determined, though, it must be possible to create a simple
+    # instance with +new+ and no parameters, since that's needed in order to
+    # call Scimitar::Resources::Mixin#scim_mutable_attributes.
   })
 
 end

data/lib/scimitar/engine.rb

@@ -1,15 +1,38 @@
+require 'rails/engine'
+
 module Scimitar
   class Engine < ::Rails::Engine
     isolate_namespace Scimitar
 
+    config.autoload_once_paths = %W(
+      #{root}/app/controllers
+      #{root}/app/models
+    )
+
     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
 
+    # Return an Array of all supported default and custom resource classes.
+    # See also :add_custom_resource and :set_default_resources.
+    #
     def self.resources
-      default_resources + custom_resources
+      self.default_resources() + self.custom_resources()
+    end
+
+    # Returns a flat array of instances of all resource schema included in the
+    # resource classes returned by ::resources.
+    #
+    def self.schemas
+      self.resources().map(&:schemas).flatten.uniq.map(&:new)
+    end
+
+    # Returns the list of custom resources, if any.
+    #
+    def self.custom_resources
+      @custom_resources ||= []
     end
 
     # Can be used to add a new resource type which is not provided by the gem.
@@ -30,7 +53,7 @@ module Scimitar
     #     Scimitar::Engine.add_custom_resource Scim::Resources::ShinyResource
     #
     def self.add_custom_resource(resource)
-      custom_resources << resource
+      self.custom_resources() << resource
     end
 
     # Resets the resource list to default. This is really only intended for use
@@ -40,23 +63,45 @@ module Scimitar
       @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:
+    # Returns the default resources added in this gem - by default, these are:
     #
     # * Scimitar::Resources::User
     # * Scimitar::Resources::Group
     #
+    # ...but if an implementation does not e.g. support Group, it can
+    # be overridden via ::set_default_resources to help with service
+    # auto-discovery.
+    #
     def self.default_resources
-      [ Resources::User, Resources::Group ]
+      @standard_default_resources = [ Resources::User, Resources::Group ]
+      @default_resources        ||= @standard_default_resources.dup()
     end
 
-    def self.schemas
-      resources.map(&:schemas).flatten.uniq.map(&:new)
+    # Override the resources returned by ::default_resources.
+    #
+    # +resource_array+:: An Array containing one or both of
+    #                    Scimitar::Resources::User and/or
+    #                    Scimitar::Resources::Group, and nothing else.
+    #
+    def self.set_default_resources(resource_array)
+      self.default_resources()
+      unrecognised_resources = resource_array - @standard_default_resources
+
+      if unrecognised_resources.any?
+        raise "Scimitar::Engine::set_default_resources: Only #{@standard_default_resources.map(&:name).join(', ')} are supported"
+      elsif resource_array.empty?
+        raise 'Scimitar::Engine::set_default_resources: At least one resource must be given'
+      end
+
+      @default_resources = resource_array
+    end
+
+    # Resets the default resource list. This is really only intended for use
+    # during testing, to avoid one test polluting another.
+    #
+    def self.reset_default_resources
+      self.default_resources()
+      @default_resources = @standard_default_resources
     end
 
   end

data/lib/scimitar/support/hash_with_indifferent_case_insensitive_access.rb

@@ -23,8 +23,8 @@ class Hash
   #
   def self.deep_indifferent_case_insensitive_access(object)
     if object.is_a?(Hash)
-      new_hash = Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess.new(object)
-      new_hash.each do | key, value |
+      new_hash = Scimitar::Support::HashWithIndifferentCaseInsensitiveAccess.new
+      object.each do | key, value |
         new_hash[key] = deep_indifferent_case_insensitive_access(value)
       end
       new_hash
@@ -49,34 +49,164 @@ module Scimitar
     # in a case-insensitive fashion too.
     #
     # During enumeration, Hash keys will always be returned in whatever case
-    # they were originally set.
+    # 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 convert_key(key)
-            key.kind_of?(Symbol) ? key.name.downcase : key.downcase
+          def scimitar_hash_with_indifferent_case_insensitive_access_string(key)
+            key.kind_of?(Symbol) ? key.name : key
           end
         else
-          def convert_key(key)
-            key.kind_of?(Symbol) ? key.to_s.downcase : key.downcase
+          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
+          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(convert_key(key), self[key], value)
+                value = block.call(self.convert_key(key), self[key], value)
               end
-              regular_writer(convert_key(key), convert_value(value))
+              self.[]=(key, value)
             end
           end
         end

data/lib/scimitar/support/utilities.rb

@@ -46,6 +46,66 @@ module Scimitar
           hash[array.shift()] = self.dot_path(array, value)
         end
       end
+
+      # Schema ID-aware splitter handling ":" or "." separators. Adapted from
+      # contribution by @bettysteger and @MorrisFreeman in:
+      #
+      #   https://github.com/RIPAGlobal/scimitar/issues/48
+      #   https://github.com/RIPAGlobal/scimitar/pull/49
+      #
+      # +schemas::   Array of extension schemas, e.g. a SCIM resource class'
+      #              <tt>scim_resource_type.extended_schemas</tt> value. The
+      #              Array should be empty if there are no extensions.
+      #
+      # +path_str+:: Path String, e.g. <tt>"password"</tt>, <tt>"name.givenName"</tt>,
+      #              <tt>"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"</tt> (special case),
+      #              <tt>"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization"</tt>
+      #              (if given a Symbol, it'll be converted to a String).
+      #
+      # Returns an array of components, e.g. <tt>["password"]</tt>, <tt>["name",
+      # "givenName"]</tt>,
+      # <tt>["urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"]</tt> (special case),
+      # <tt>["urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "organization"]</tt>.
+      #
+      # The called-out special case is for a schema ID without any appended
+      # path components, which is returned as a single element ID to aid in
+      # traversal particularly of things like PATCH requests. There, a "value"
+      # attribute might have a key string that's simply a schema ID, with an
+      # object beneath that's got attribute-name pairs, possibly nested, in a
+      # path-free payload.
+      #
+      def self.path_str_to_array(schemas, path_str)
+        path_str   = path_str.to_s
+        components = []
+
+        # Note the ":" separating the schema ID (URN) from the attribute.
+        # The nature of JSON rendering / other payloads might lead you to
+        # expect a "." as with any complex types, but that's not the case;
+        # see https://tools.ietf.org/html/rfc7644#section-3.10, or
+        # https://tools.ietf.org/html/rfc7644#section-3.5.2 of which in
+        # particular, https://tools.ietf.org/html/rfc7644#page-35.
+        #
+        if path_str.include?(':')
+          lower_case_path_str = path_str.downcase()
+
+          schemas.each do |schema|
+            lower_case_schema_id       = schema.id.downcase()
+            attributes_after_schema_id = lower_case_path_str.split(lower_case_schema_id + ':').drop(1)
+
+            if attributes_after_schema_id.empty?
+              components += [schema.id] if lower_case_path_str == lower_case_schema_id
+            else
+              attributes_after_schema_id.each do |component|
+                components += [schema.id] + component.split('.')
+              end
+            end
+          end
+        end
+
+        components = path_str.split('.') if components.empty?
+        return components
+      end
+
     end
   end
 end

data/lib/scimitar/version.rb

@@ -3,11 +3,11 @@ module Scimitar
   # Gem version. If this changes, be sure to re-run "bundle install" or
   # "bundle update".
   #
-  VERSION = '1.8.1'
+  VERSION = '1.10.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2024-01-16'
+  DATE = '2024-06-27'
 
 end

data/spec/apps/dummy/app/models/mock_user.rb

@@ -18,6 +18,7 @@ class MockUser < ActiveRecord::Base
     work_phone_number
     organization
     department
+    manager
     mock_groups
   }
 
@@ -48,6 +49,7 @@ class MockUser < ActiveRecord::Base
       externalId: :scim_uid,
       userName:   :username,
       password:   :password,
+      active:     :is_active,
       name:       {
         givenName:  :first_name,
         familyName: :last_name
@@ -80,8 +82,11 @@ class MockUser < ActiveRecord::Base
           }
         },
       ],
-      groups: [ # NB read-only, so no :find_with key
+      groups: [
         {
+          # Read-only, so no :find_with key. There's no 'class' specified here
+          # either, to help test the "/Schemas" endpoint's reflection code.
+          #
           list:  :mock_groups,
           using: {
             value:   :id,
@@ -89,13 +94,16 @@ class MockUser < ActiveRecord::Base
           }
         }
       ],
-      active: :is_active,
 
       # Custom extension schema - see configuration in
       # "spec/apps/dummy/config/initializers/scimitar.rb".
       #
       organization: :organization,
       department:   :department,
+      primaryEmail: :scim_primary_email,
+
+      manager:      :manager,
+
       userGroups: [
         {
           list:      :mock_groups,
@@ -124,9 +132,16 @@ class MockUser < ActiveRecord::Base
       'groups.value'      => { column: MockGroup.arel_table[:id] },
       'emails'            => { columns: [ :work_email_address, :home_email_address ] },
       'emails.value'      => { columns: [ :work_email_address, :home_email_address ] },
-      'emails.type'       => { ignore: true } # We can't filter on that; it'll just search all e-mails
+      'emails.type'       => { ignore: true }, # We can't filter on that; it'll just search all e-mails
+      'primaryEmail'      => { column: :scim_primary_email },
     }
   end
 
+  # Custom attribute reader
+  #
+  def scim_primary_email
+    work_email_address
+  end
+
   include Scimitar::Resources::Mixin
 end

data/spec/apps/dummy/config/initializers/scimitar.rb

@@ -40,10 +40,13 @@ Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
 
 module ScimSchemaExtensions
   module User
+
+    # This "looks like" part of the standard Enterprise extension.
+    #
     class Enterprise < Scimitar::Schema::Base
       def initialize(options = {})
         super(
-          name:            'ExtendedUser',
+          name:            'EnterpriseExtendedUser',
           description:     'Enterprise extension for a User',
           id:              self.class.id,
           scim_attributes: self.class.scim_attributes
@@ -57,7 +60,32 @@ module ScimSchemaExtensions
       def self.scim_attributes
         [
           Scimitar::Schema::Attribute.new(name: 'organization', type: 'string'),
-          Scimitar::Schema::Attribute.new(name: 'department',   type: 'string')
+          Scimitar::Schema::Attribute.new(name: 'department',   type: 'string'),
+          Scimitar::Schema::Attribute.new(name: 'primaryEmail', type: 'string'),
+        ]
+      end
+    end
+
+    # In https://github.com/RIPAGlobal/scimitar/issues/122 we learn that with
+    # more than one extension, things can go wrong - so now we test with two.
+    #
+    class Manager < Scimitar::Schema::Base
+      def initialize(options = {})
+        super(
+          name:            'ManagementExtendedUser',
+          description:     'Management extension for a User',
+          id:              self.class.id,
+          scim_attributes: self.class.scim_attributes
+        )
+      end
+
+      def self.id
+        'urn:ietf:params:scim:schemas:extension:manager:1.0:User'
+      end
+
+      def self.scim_attributes
+        [
+          Scimitar::Schema::Attribute.new(name: 'manager', type: 'string')
         ]
       end
     end
@@ -65,3 +93,4 @@ module ScimSchemaExtensions
 end
 
 Scimitar::Resources::User.extend_schema ScimSchemaExtensions::User::Enterprise
+Scimitar::Resources::User.extend_schema ScimSchemaExtensions::User::Manager

data/spec/apps/dummy/db/migrate/20210304014602_create_mock_users.rb

@@ -19,6 +19,7 @@ class CreateMockUsers < ActiveRecord::Migration[6.1]
       #
       t.text :organization
       t.text :department
+      t.text :manager
     end
   end
 end

data/spec/apps/dummy/db/schema.rb

@@ -42,6 +42,7 @@ ActiveRecord::Schema.define(version: 2021_03_08_044214) do
     t.text "work_phone_number"
     t.text "organization"
     t.text "department"
+    t.text "manager"
   end
 
   add_foreign_key "mock_groups_users", "mock_groups"