scimitar 2.8.0 → 2.10.0

data/app/models/scimitar/resources/base.rb

@@ -35,14 +35,45 @@ module Scimitar
         @errors = ActiveModel::Errors.new(self)
       end
 
+      # Scimitar has at present a general limitation in handling schema IDs,
+      # which just involves stripping them and requiring attributes across all
+      # extension schemas to be overall unique.
+      #
+      # This method takes an options payload for the initializer and strips out
+      # *recognised* schema IDs, so that the resulting attribute data matches
+      # the resource attribute map.
+      #
+      # +attributes+:: Attributes to assign via initializer; typically a POST
+      #                payload of attributes that has been run through Rails
+      #                strong parameters for safety.
+      #
+      # Returns a new object of the same class as +options+ with recognised
+      # schema IDs removed.
+      #
       def flatten_extension_attributes(options)
-        flattened = options.dup
-        self.class.extended_schemas.each do |extended_schema|
-          if extension_attrs = flattened.delete(extended_schema.id)
-            flattened.merge!(extension_attrs)
+        flattened             = options.class.new
+        lower_case_schema_ids = self.class.extended_schemas.map do | schema |
+          schema.id.downcase()
+        end
+
+        options.each do | key, value |
+          path = Scimitar::Support::Utilities::path_str_to_array(
+            self.class.extended_schemas,
+            key
+          )
+
+          if path.first.include?(':') && lower_case_schema_ids.include?(path.first.downcase)
+            path.shift()
+          end
+
+          if path.empty?
+            flattened.merge!(value)
+          else
+            flattened[path.join('.')] = value
           end
         end
-        flattened
+
+        return flattened
       end
 
       # Can be used to extend an existing resource type's schema. For example:
@@ -127,7 +158,7 @@ module Scimitar
         hash.with_indifferent_access.each_pair do |attr_name, attr_value|
           scim_attribute = self.class.complex_scim_attributes[attr_name].try(:first)
 
-          if scim_attribute && scim_attribute.complexType
+          if scim_attribute&.complexType
             if scim_attribute.multiValued
               self.send("#{attr_name}=", attr_value&.map {|attr_for_each_item| complex_type_from_hash(scim_attribute, attr_for_each_item)})
             else

data/app/models/scimitar/resources/mixin.rb

@@ -139,11 +139,12 @@ module Scimitar
     #       # ...
     #       groups: [
     #         {
-    #           list: :users,          # <-- i.e. Team.users,
+    #           list:  :users,         # <-- i.e. Team.users,
     #           using: {
     #             value:   :id,        # <-- i.e. Team.users[n].id
     #             display: :full_name  # <-- i.e. Team.users[n].full_name
     #           },
+    #           class: Team, # Optional; see below
     #           find_with: -> (scim_list_entry) {...} # See below
     #         }
     #       ],
@@ -159,7 +160,10 @@ module Scimitar
     # example above, "find_with"'s Proc might look at a SCIM entry value which
     # is expected to be a user ID and find that User. The mapped set of User
     # data thus found would be written back with "#users=", due to the ":list"
-    # key declaring the method name ":users".
+    # key declaring the method name ":users". The optional "class" key is
+    # recommended but not really *needed* unless the configuration option
+    # Scimitar::EngineConfiguration::schema_list_from_attribute_mappings is
+    # defined; see documentation of that option for more information.
     #
     # Note that you can only use either:
     #
@@ -176,7 +180,8 @@ module Scimitar
     # == scim_mutable_attributes
     #
     # Define this method to return a Set (preferred) or Array of names of
-    # attributes which may be written in the mixing-in class.
+    # attributes which may be written in the mixing-in class. The names MUST be
+    # expressed as Symbols, *not* Strings.
     #
     # If you return +nil+, it is assumed that +any+ attribute mapped by
     # ::scim_attributes_map which has a write accessor will be eligible for
@@ -291,7 +296,7 @@ module Scimitar
         # the result in an instance variable.
         #
         def scim_mutable_attributes
-          @scim_mutable_attributes ||= self.class.scim_mutable_attributes()
+          @scim_mutable_attributes ||= self.class.scim_mutable_attributes()&.map(&:to_sym)
 
           if @scim_mutable_attributes.nil?
             @scim_mutable_attributes = Set.new
@@ -468,7 +473,7 @@ module Scimitar
             path_str = operation['path' ]
             value    = operation['value']
 
-            unless ['add', 'remove', 'replace'].include?(nature)
+            unless %w[add remove replace].include?(nature)
               raise Scimitar::InvalidSyntaxError.new("Unrecognised PATCH \"op\" value of \"#{nature}\"")
             end
 
@@ -608,7 +613,7 @@ module Scimitar
                 built_dynamic_list = false
                 mapped_array = attrs_map_or_leaf_value.map do |value|
                   if ! value.is_a?(Hash)
-                    raise 'Bad attribute map: Array contains someting other than mapping Hash(es)'
+                    raise 'Bad attribute map: Array contains something other than mapping Hash(es)'
 
                   elsif value.key?(:match) # Static map
                     static_hash = { value[:match] => value[:with] }
@@ -736,7 +741,7 @@ module Scimitar
           # +path+::                    Array of SCIM attribute names giving a
           #                             path into the SCIM schema where
           #                             iteration has reached. Used to find the
-          #                             schema attribute definiton and check
+          #                             schema attribute definition and check
           #                             mutability before writing.
           #
           def from_scim_backend!(
@@ -1083,7 +1088,7 @@ module Scimitar
                     # associated collection or clearing a local model attribute
                     # directly to "nil").
                     #
-                    if handled == false
+                    unless handled
                       current_data_at_path[matched_index] = nil
                       compact_after = true
                     end
@@ -1285,7 +1290,7 @@ module Scimitar
                       end
                     end
 
-                    if handled == false
+                    unless handled
                       altering_hash[path_component] = []
                     end
 
@@ -1440,7 +1445,7 @@ module Scimitar
           #     { value: :work_email }
           #
           # If there was a SCIM entry with a type of something unrecognised,
-          # such as 'holday', then +nil+ would be returned since there is no
+          # such as 'holiday', then +nil+ would be returned since there is no
           # matching attribute map entry.
           #
           # Note that the <tt>:with_attr_map</tt> array can contain dynamic

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

@@ -36,7 +36,7 @@ module Scimitar
         scim_attributes.map { |scim_attribute| scim_attribute.clone }
       end
 
-      # Find a given attribute this schema, travelling down a path to any
+      # Find a given attribute of this schema, travelling down a path to any
       # sub-attributes within. Given that callers might be dealing with paths
       # into actual SCIM data, array indices for multi-value attributes are
       # allowed (as integers) and simply skipped - only the names are of

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

@@ -15,8 +15,24 @@ module Scimitar
       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.
@@ -37,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
@@ -47,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/utilities.rb

@@ -57,9 +57,10 @@ module Scimitar
       #              <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>,
+      # +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>,
@@ -74,6 +75,7 @@ module Scimitar
       # 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.
@@ -84,11 +86,14 @@ module Scimitar
         # particular, https://tools.ietf.org/html/rfc7644#page-35.
         #
         if path_str.include?(':')
+          lower_case_path_str = path_str.downcase()
+
           schemas.each do |schema|
-            attributes_after_schema_id = path_str.downcase.split(schema.id.downcase + ':').drop(1)
+            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]
+              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('.')

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 = '2.8.0'
+  VERSION = '2.10.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2024-06-13'
+  DATE = '2024-10-22'
 
 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,7 +94,6 @@ class MockUser < ActiveRecord::Base
           }
         }
       ],
-      active: :is_active,
 
       # Custom extension schema - see configuration in
       # "spec/apps/dummy/config/initializers/scimitar.rb".
@@ -97,6 +101,9 @@ class MockUser < ActiveRecord::Base
       organization: :organization,
       department:   :department,
       primaryEmail: :scim_primary_email,
+
+      manager:      :manager,
+
       userGroups: [
         {
           list:      :mock_groups,
@@ -130,7 +137,8 @@ class MockUser < ActiveRecord::Base
     }
   end
 
-  # reader
+  # Custom attribute reader
+  #
   def scim_primary_email
     work_email_address
   end

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

@@ -33,10 +33,13 @@ Rails.application.config.to_prepare do
 
   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
@@ -55,8 +58,33 @@ Rails.application.config.to_prepare do
           ]
         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
     end
   end
 
   Scimitar::Resources::User.extend_schema ScimSchemaExtensions::User::Enterprise
+  Scimitar::Resources::User.extend_schema ScimSchemaExtensions::User::Manager
 end

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

@@ -41,6 +41,7 @@ ActiveRecord::Schema[7.1].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"

data/spec/controllers/scimitar/resource_types_controller_spec.rb

@@ -9,11 +9,15 @@ RSpec.describe Scimitar::ResourceTypesController do
     it 'renders the resource type for user' do
       get :index, format: :scim
       response_hash = JSON.parse(response.body)
-      expected_response = [ Scimitar::Resources::User.resource_type(scim_resource_type_url(name: 'User', test: 1)),
-                            Scimitar::Resources::Group.resource_type(scim_resource_type_url(name: 'Group', test: 1))
-      ].to_json
+      expected_response = {
+        schemas: ['urn:ietf:params:scim:api:messages:2.0:ListResponse'],
+        totalResults: 2,
+        Resources: [
+          Scimitar::Resources::User.resource_type(scim_resource_type_url(name: 'User', test: 1)),
+          Scimitar::Resources::Group.resource_type(scim_resource_type_url(name: 'Group', test: 1))
+        ]
+      }.to_json
 
-      response_hash = JSON.parse(response.body)
       expect(response_hash).to eql(JSON.parse(expected_response))
     end