scimitar 2.12.0 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e8493f9f42ec39cc98639167c39e60261400208a011e21d202116d5ca43daff
-  data.tar.gz: fb1fe271b42006d0e0054207d873b18ad15851d76597bf78c591f2254eab6688
+  metadata.gz: c5f63ca5b1572be0cb53a95a47280099713fd32be8f5650396a0db6a0c92550e
+  data.tar.gz: 2f1f2a7ec7a6877607875f6b86e7b9859ae9124f71d295541847940dd31c8b1f
 SHA512:
-  metadata.gz: 4f2d68d767cdf33d97684697466dbca05122783f6a081010f874ef8546cc684c3fe9ca8c72478c6214a7493ffc3d80dfd8a742d03c0748968a32b3dc76980e05
-  data.tar.gz: 456146fa9cd91c44208e689ba4ba5663626e4ba8bcd3fbdcd592e78785e5af63449d41e68c465e84f8567352a505d02a200b8fbca36b38b7a9d61bc7784b73b8
+  metadata.gz: '08626642f4b3e9dd29a6141c72bea784ab094ec197d9f3b9278957a59bfe230f4ef7ec84d52b1584127af647809351607bc01ef408d7269cc39dcf1f17180d49'
+  data.tar.gz: 53845ba684f54f8e2e90e696b769aadfe803809fa3004fa35f779794d6e04bfa034ee231847382591cdc5600cc7544bbad4c959e2031c0271e67e5632d431f6c

data/README.md

@@ -64,7 +64,7 @@ Some aspects of configuration are handled via a `config/initializers/scimitar.rb
 Rails.application.config.to_prepare do
   Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
     # ...see subsections below for configuration options...
-  end
+  })
 end
 ```
 
@@ -123,7 +123,7 @@ Here's an example where Warden is being used for authentication, with Warden sto
 
 ```ruby
 Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
-  custome_authenticator: Proc.new do
+  custom_authenticator: Proc.new do
 
     # In this example we catch the Warden 'throw' for failed authentication, as
     # well as allowing Warden to successfully find an *authenticated* user, but
@@ -184,7 +184,36 @@ Note that Okta has some [curious documentation on its use of `POST` vs `PATCH` f
 
 ### Google Workspace note
 
-Using SCIM with Google Workspace might only work for a subset of applications. Since web UIs for major service providers change very often, it doesn't make sense to provide extensive documentation here as it would get out of date quickly; you may have to figure out the setup as best you can using whatever current Google documentation exists for their system. There are [some notes which were relevant around mid-2025](https://github.com/pond/scimitar/issues/142#issuecomment-2699050541) (from when a workarond/fix was incorporated into Scimitar to allow it to work with Google Workspace) which may help you get started.
+Using SCIM with Google Workspace might only work for a subset of applications. Since web UIs for major service providers change very often, it doesn't make sense to provide extensive documentation here as it would get out of date quickly; you may have to figure out the setup as best you can using whatever current Google documentation exists for their system. There are [some notes which were relevant around mid-2025](https://github.com/pond/scimitar/issues/142#issuecomment-2699050541) (from when a workaround/fix was incorporated into Scimitar to allow it to work with Google Workspace) which may help you get started.
+
+### Request content type handling
+
+The correct content type for SCIM is `application/scim+json`. Scimitar tolerates some variants of this, rewriting things internally so that the request continues to be processed by the rest of the gem (including ending up in subclass code you write) under this media type, with a Rails request format of `:scim`. Sometimes, callers into SCIM endpoints might use a content type that Scimitar rejects. If so, you can configure a custom request sanitizer Proc (with a "z", in keeping with Rails spelling of "sanitize"):
+
+```ruby
+Rails.application.config.to_prepare do
+  Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
+
+    custom_request_sanitizer: Proc.new do | request |
+      #
+      # Examine e.g. 'request.media_type' and evaluate to a Symbol:
+      #
+      #   :success  - set the standard content type and ensure the Rails request
+      #               format is :scim; continue processing normally
+      #
+      #   :preserve - retain the existing content type and Rails request format;
+      #               continue processing normally
+      #
+      #   :fail     - the request format appears to be invalid; generate a 406
+      #               ("Not Acceptable") response
+      #
+    end
+
+  })
+end
+```
+
+The Proc is passed the [`ActionDispatch::Request`](https://api.rubyonrails.org/classes/ActionDispatch/Request.html) instance for the current request. It **must** evaluable to a Symbol as shown above. Typically, `:preserve` is only for very special use cases where you understand that the request headers and/or format might not match what other parts of Scimitar expect, but have written appropriate custom code elsewhere to deal with that.
 
 ### Data models
 
@@ -255,8 +284,8 @@ class User < ActiveRecord::Base
       ],
 
       # NB The 'groups' collection in a SCIM User resource is read-only, so
-      #    we provide no ":find_with" key for looking up records for writing
-      #    updates to the associated collection.
+      #    we provide no ":find_with" or ":find_all_with" key for looking up
+      #    records for writing updates to the associated collection.
       #
       groups: [
         {

data/app/controllers/scimitar/application_controller.rb

@@ -93,16 +93,37 @@ module Scimitar
       #
       def require_scim
         scim_mime_type = Mime::Type.lookup_by_extension(:scim).to_s
+        failure_detail = "Only #{scim_mime_type} type is accepted."
+
+        if Scimitar.engine_configuration.custom_request_sanitizer.is_a?(Proc)
+
+          result = Scimitar.engine_configuration.custom_request_sanitizer.call(request)
+          case result
+            when :fail
+              handle_scim_error(ErrorResponse.new(status: 406, detail: failure_detail))
+            when :preserve
+              # Do nothing
+            else
+              request.format = :scim
+              request.headers['CONTENT_TYPE'] = scim_mime_type
+          end
+
+        else # "if Scimitar.engine_configuration.custom_request_sanitizer.present?"
+
+          if request.media_type.nil? || request.media_type.empty?
+            request.format = :scim
+            request.headers['CONTENT_TYPE'] = scim_mime_type
+          elsif request.media_type.downcase == scim_mime_type
+            request.format = :scim
+          elsif request.format == :scim
+            request.headers['CONTENT_TYPE'] = scim_mime_type
+          elsif request.media_type.downcase == 'application/json' && request.user_agent&.start_with?('Google') # https://github.com/pond/scimitar/issues/142
+            request.format = :scim
+            request.headers["CONTENT_TYPE"] = scim_mime_type
+          else
+            handle_scim_error(ErrorResponse.new(status: 406, detail: failure_detail))
+          end
 
-        if request.media_type.nil? || request.media_type.empty?
-          request.format = :scim
-          request.headers['CONTENT_TYPE'] = scim_mime_type
-        elsif request.media_type.downcase == scim_mime_type
-          request.format = :scim
-        elsif request.format == :scim
-          request.headers['CONTENT_TYPE'] = scim_mime_type
-        else
-          handle_scim_error(ErrorResponse.new(status: 406, detail: "Only #{scim_mime_type} type is accepted."))
         end
       end
 

data/app/models/scimitar/engine_configuration.rb

@@ -12,6 +12,7 @@ module Scimitar
       :basic_authenticator,
       :token_authenticator,
       :custom_authenticator,
+      :custom_request_sanitizer,
       :application_controller_mixin,
       :exception_reporter,
       :optional_value_fields_required,

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

@@ -145,7 +145,8 @@ module Scimitar
     #             display: :full_name  # <-- i.e. Team.users[n].full_name
     #           },
     #           class: Team, # Optional; see below
-    #           find_with: -> (scim_list_entry) {...} # See below
+    #           find_with:     -> (scim_list_entry) {...}, # See below
+    #           find_all_with: -> (scim_list_entries) {...} # Optional, See below
     #         }
     #       ],
     #       #...
@@ -165,6 +166,11 @@ module Scimitar
     # Scimitar::EngineConfiguration::schema_list_from_attribute_mappings is
     # defined; see documentation of that option for more information.
     #
+    # To avoid N+1 queries when resolving many entries (e.g. Group members
+    # during PATCH), you can instead provide ":find_all_with" which is passed
+    # the entire Array of SCIM entries and should return an Array of resolved
+    # model instances. If both are provided, ":find_all_with" is preferred.
+    #
     # Note that you can only use either:
     #
     # * One or more static maps where each matches some other piece of source
@@ -315,7 +321,7 @@ module Scimitar
                     enum.each do | static_or_dynamic_mapping |
                       if static_or_dynamic_mapping.key?(:match) # Static
                         extractor.call(static_or_dynamic_mapping[:using])
-                      elsif static_or_dynamic_mapping.key?(:find_with) # Dynamic
+                      elsif static_or_dynamic_mapping.key?(:find_with) || static_or_dynamic_mapping.key?(:find_all_with) # Dynamic
                         @scim_mutable_attributes << static_or_dynamic_mapping[:list]
                       end
                     end
@@ -839,9 +845,17 @@ module Scimitar
                     method    = "#{mapped_array_entry[:list]}="
 
                     if (attribute&.mutability == 'readWrite' || attribute&.mutability == 'writeOnly') && self.respond_to?(method)
-                      find_with_proc = mapped_array_entry[:find_with]
+                      find_all_with_proc = mapped_array_entry[:find_all_with]
+                      find_with_proc     = mapped_array_entry[:find_with]
+
+                      if find_all_with_proc.respond_to?(:call)
+                        scim_entries = (scim_hash_or_leaf_value || [])
+                        mapped_list  = find_all_with_proc.call(scim_entries) || []
 
-                      unless find_with_proc.nil?
+                        mapped_list.compact!
+
+                        self.public_send(method, mapped_list)
+                      elsif find_with_proc.respond_to?(:call)
                         mapped_list = (scim_hash_or_leaf_value || []).map do | source_list_entry |
                           find_with_proc.call(source_list_entry)
                         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 = '2.12.0'
+  VERSION = '2.14.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2025-08-15'
+  DATE = '2025-11-14'
 
 end

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

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

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

@@ -0,0 +1,20 @@
+class MockGroupBatch < MockGroup
+  def self.scim_attributes_map
+    {
+      id:          :id,
+      externalId:  :scim_uid,
+      displayName: :display_name,
+      members:     [
+        {
+          list:  :scim_users_and_groups,
+          using: { value: :id },
+          # Minimal mock: assume user-only entries (type omitted => User)
+          find_all_with: -> (entries) do
+            ids = entries.map { |e| e['value'] }
+            MockUser.where(primary_key: ids).to_a
+          end
+        }
+      ]
+    }
+  end
+end

data/spec/apps/dummy/config/routes.rb

@@ -17,6 +17,12 @@ Rails.application.routes.draw do
   get    'Groups/:id', to: 'mock_groups#show'
   patch  'Groups/:id', to: 'mock_groups#update'
 
+  # Batch lookup variant for testing the mixin 'find_all_with' option.
+  #
+  get    'BatchGroups',     to: 'mock_batch_groups#index'
+  get    'BatchGroups/:id', to: 'mock_batch_groups#show'
+  patch  'BatchGroups/:id', to: 'mock_batch_groups#update'
+
   # For testing blocks passed to ActiveRecordBackedResourcesController#create,
   # #update, #replace and #destroy.
   #

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -416,6 +416,80 @@ RSpec.describe Scimitar::ApplicationController do
           expect(@exception.message).to eql('Only application/scim+json type is accepted.')
         end
       end
+
+      context 'and with Google SCIM calls' do
+        it 'reaches the controller action if the expected agent is making the request' do
+          request.headers['Content-Type'] = 'application/json'
+          request.headers['User-Agent'  ] = 'Google-Auto-Provisioning'
+          get :index
+
+          expect(@exception).to be_a(RuntimeError)
+          expect(@exception.message).to eql('Bang')
+        end
+
+        it 'is invoked early for unrecognised agents' do
+          request.headers['Content-Type'] = 'application/json'
+          get :index
+
+          expect(@exception).to be_a(Scimitar::ErrorResponse)
+          expect(@exception.message).to eql('Only application/scim+json type is accepted.')
+        end
+      end # "context 'and with Google SCIM calls' do"
+
+      context 'and with a custom request sanitizer' do
+        around :each do | example |
+          original_configuration = Scimitar.engine_configuration.custom_request_sanitizer
+          Scimitar.engine_configuration.custom_request_sanitizer = Proc.new do | request |
+            case request.media_type
+              when 'application/json+success'
+                :success
+              when 'application/json+preserve'
+                :preserve
+              else
+                :fail
+            end
+          end
+          example.run()
+        ensure
+          Scimitar.engine_configuration.custom_request_sanitizer = original_configuration
+        end
+
+        context 'returning "success"' do
+          it 'reaches the controller action with cleaned up request data' do
+            request.headers['Content-Type'] = 'application/json+success'
+            get :index
+
+            expect(@exception).to be_a(RuntimeError)
+            expect(@exception.message).to eql('Bang')
+
+            expect(request.format == :scim).to eql(true)
+            expect(request.headers['CONTENT_TYPE']).to eql('application/scim+json')
+          end
+        end # "context 'returning "success"' do"
+
+        context 'returning "preserve"' do
+          it 'reaches the controller action with unmodified request data' do
+            request.headers['Content-Type'] = 'application/json+preserve'
+            get :index
+
+            expect(@exception).to be_a(RuntimeError)
+            expect(@exception.message).to eql('Bang')
+
+            expect(request.format == :html).to eql(true)
+            expect(request.headers['CONTENT_TYPE']).to eql('application/json+preserve')
+          end
+        end # "context 'returning "keep"' do"
+
+        context 'returning "fail"' do
+          it 'is invoked' do
+            request.headers['Content-Type'] = 'application/json+fail'
+            get :index
+
+            expect(@exception).to be_a(Scimitar::ErrorResponse)
+            expect(@exception.message).to eql('Only application/scim+json type is accepted.')
+          end
+        end # "context 'returning "fail"' do"
+      end # "context 'and with a custom request sanitizer' do"
     end # "context 'exception reporter' do"
   end # "context 'error handling' do"
 end

data/spec/requests/active_record_backed_resources_controller_spec.rb

@@ -1137,6 +1137,39 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
         expect(@u2.password).to eql('correcthorsebatterystaple')
       end
 
+      context "when updating group members using :find_all_with" do
+        it "uses :find_all_with to batch-resolve users and updates associations" do
+          payload = {
+            schemas: [ 'urn:ietf:params:scim:api:messages:2.0:PatchOp' ],
+            Operations: [
+              {
+                op:   'add',
+                path: 'members',
+                value: [
+                  { 'value' => @u1.primary_key },
+                  { 'value' => @u2.primary_key }
+                ]
+              }
+            ]
+          }
+
+          payload = spec_helper_hupcase(payload) if force_upper_case
+
+          patch "/BatchGroups/#{@g1.id}", params: payload.merge({ format: :scim })
+
+          expect(response.status).to eql(200)
+
+          # Verify membership updated
+          get "/BatchGroups/#{@g1.id}", params: { format: :scim }
+          expect(response.status).to eql(200)
+          result = JSON.parse(response.body)
+
+          values = result.fetch('members', []).map { |m| m['value'] }
+          expect(values).to include(@u1.primary_key.to_s)
+          expect(values).to include(@u2.primary_key.to_s)
+        end
+      end
+
       context 'which clears attributes' do
         before :each do
           @u2.update!(work_email_address: 'work_2@test.com')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 2.12.0
+  version: 2.14.0
 platform: ruby
 authors:
 - RIPA Global
 - Andrew David Hodgkinson
 bindir: bin
 cert_chain: []
-date: 2025-08-15 00:00:00.000000000 Z
+date: 2025-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.2'
+        version: '13.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.2'
+        version: '13.3'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.14'
+        version: '6.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.14'
+        version: '6.15'
 - !ruby/object:Gem::Dependency
   name: warden
   requirement: !ruby/object:Gem::Requirement
@@ -230,9 +230,11 @@ files:
 - spec/apps/dummy/app/controllers/custom_request_verifiers_controller.rb
 - spec/apps/dummy/app/controllers/custom_save_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb
+- spec/apps/dummy/app/controllers/mock_batch_groups_controller.rb
 - spec/apps/dummy/app/controllers/mock_groups_controller.rb
 - spec/apps/dummy/app/controllers/mock_users_controller.rb
 - spec/apps/dummy/app/models/mock_group.rb
+- spec/apps/dummy/app/models/mock_group_batch.rb
 - spec/apps/dummy/app/models/mock_user.rb
 - spec/apps/dummy/config/application.rb
 - spec/apps/dummy/config/boot.rb
@@ -304,9 +306,11 @@ test_files:
 - spec/apps/dummy/app/controllers/custom_request_verifiers_controller.rb
 - spec/apps/dummy/app/controllers/custom_save_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb
+- spec/apps/dummy/app/controllers/mock_batch_groups_controller.rb
 - spec/apps/dummy/app/controllers/mock_groups_controller.rb
 - spec/apps/dummy/app/controllers/mock_users_controller.rb
 - spec/apps/dummy/app/models/mock_group.rb
+- spec/apps/dummy/app/models/mock_group_batch.rb
 - spec/apps/dummy/app/models/mock_user.rb
 - spec/apps/dummy/config/application.rb
 - spec/apps/dummy/config/boot.rb